4

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.

makeyourownmaker
  • 1,164
  • 1
  • 9
  • 29
  • 1
    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. – chepner Jun 24 '20 at 18:43
  • 1
    (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.) – chepner Jun 24 '20 at 18:45
  • 2
    @chepner I chose the bare repository dotfiles management approach to **avoid** using symlinks. – makeyourownmaker Jun 24 '20 at 18:52

5 Answers5

7

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

Biloubilou
  • 86
  • 2
  • That works :-) Thank you ever so much for your answer! FWIW what you describe is documented [here](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/about-readmes) – makeyourownmaker Aug 05 '20 at 20:28
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.

LeGEC
  • 29,595
  • 2
  • 37
  • 78
1

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.

makeyourownmaker
  • 1,164
  • 1
  • 9
  • 29
  • 1
    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. https://github.com/anandpiyer/.dotfiles – mrossman Jul 22 '20 at 21:08
  • 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! – makeyourownmaker Jul 22 '20 at 21:30
  • Added as an [answer](https://stackoverflow.com/a/63057672/8371763) – mrossman Jul 23 '20 at 15:22
1

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.

mrossman
  • 377
  • 2
  • 9
  • `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? – nipunravisara Feb 28 '21 at 02:01
  • 1
    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. – mrossman Feb 28 '21 at 02:52
  • Oh I get it. Thanks. I'll try. – nipunravisara Feb 28 '21 at 04:09
-4

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

Alejandro Barrios
  • 17
  • 2
  • 3
    Adding a tracked file to `.gitignore` doesn't make sense — `.gitignore` ignores only **untracked** files. – phd Jun 24 '20 at 19:50
  • 4
    `git rm -r --cached .` This advice is even worse, it deletes everything from the repo so the OP would loose all his files. – phd Jun 24 '20 at 19:51