How to add README.md on github but not have same README.md in home directory while using a bare git repository for managing dotfiles?

Question

I manage my dotfiles using git in a bare repository. See article by Harfang Perch for details on this method.

It works great but I'd like to add a README.md to the root of the repository on github.

How do I add a README.md to the github repository root directory but not have that file show up in my home directories?

If I push a README.md to github then delete the README.md in my home directory this will result in

deleted:    README.md

messages from git --git-dir=$HOME/.dotfiles/ --work-tree=$HOME status which I'd prefer to avoid.

As far as I'm aware github only renders README and README.md files in the repository root (and sub-directories but that's not relevant for this question).

I haven't seen other github dotfile bare repositories with README.md files but I've only checked 5.

Github wiki pages don't solve this problem unless there is some magic to display them in the root of the repository using a hidden .dotfile. Perhaps I'm grasping at straws but, is there any way to link and display a gist in the repository root directory on github?

I don't currently use gitlab but moving to gitlab, or a similar git hosting service, is a possibility if they have support for this that github does not.

Remington

I would recommend not using a bare repository here. Keep the repository in a single .dotfiles directory, and create symlinks like $HOME/.bashrc -> $HOME/.dotfiles/.bashrc as needed. You can write a script to create all the necessary symlinks and store that in the repository as well. – Jonell

(Many, though not all, programs may also look in a standard location like ~/.config for configuration files, which means you can simply clone your .dotfiles as .config instead. Such programs will probably honor a standard environment variable that specifies which directory contains the configuration, meaning the only file you need in ~ directly is the shell configuration file sets that environment variable.) – Jonell

@Jonell I chose the bare repository dotfiles management approach to avoid using symlinks. – Remington

Answer 1

You can put your README file in a .github folder and it will be automatically detected on github to be displayed on your repo main view

Nammu

That works :-) Thank you ever so much for your answer! FWIW what you describe is documented here – Remington

Answer 2

The Readme.md displayed by default on GitHub is the one in the master branch.

You could create a home branch that wouldn't have the Readme, and use that branch as a work branch.

You would probably want to merge to master on a regular basis, you could add one or two convenient aliases to do this in one go, either when committing or when pushing.

---

You could try to get clever with subtrees too.

Peel

Answer 3

Although not ideal, one simple solution is to put your README and any other meta-files about your configuration into a tracked .dotfiles directory. You can then link to the README file in your repo's about section on GitHub.

An example of this setup: https://github.com/anandpiyer/.dotfiles

Upon trying this myself, I realized my repo itself is stored in a .dotfiles directory so the README gets mixed in with the internal Git files. However, placing it in ~/.dotfiles/README.md and adding/pushing worked as expected. You could try a different directory name like .about if you don't want it mixed in.

Gypsie

README.md is located on .dotfiles folder of your repo. Is this README.md is commom for every branch ?. Because in my configs actually I need to manage different branches which contains different themes so I would like to add screenshots to that README which shows in every branch. Is it possible? – Perceivable

I think you would need to pull the latest README into each branch to have it shared like you're describing, maybe a script could help automate this. – Gypsie

Oh I get it. Thanks. I'll try. – Perceivable

Answer 4

The best I can do for now is to link to a gist from the About section.

The About section is displayed on the right-hand side of github repository pages.

Remington

Here is an example I found that uses the about section to link to a README in a .dotfiles folder so it stays self-contained. github.com/anandpiyer/.dotfiles – Gypsie

That is preferable to the link I have in the About section to a separate gist. Consider adding it as an answer. Well spotted example! – Remington

Added as an answer – Gypsie

Answer 5

Look at the documentation here for README.md https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes

If you put your README file in your repository's hidden .github, root, or docs directory, GitHub will recognize and automatically surface your README to repository visitors.

If a repository contains more than one README file, then the file shown is chosen from locations in the following order: the .github directory, then the repository's root directory, and finally the docs directory.

So .github, / and docs/

Aliaalias

I know this post is old– but this answer is clearer on all the different directories you could display README. – Aliaalias

Answer 6

commit and push the correct readme file to your repository,

add the readme file in your .gitignore file and now u can change the readme file in your computer and commit your changes without any problem.

if git not ignore the readme file, try:

commit all your changes and run

git rm -r --cached . 

for reset the followed files on git

Chocolate

Adding a tracked file to .gitignore doesn't make sense — .gitignore ignores only untracked files. – Butterwort

git rm -r --cached . This advice is even worse, it deletes everything from the repo so the OP would loose all his files. – Butterwort