Configure github to use some other file as README
github
Solution
- In the root directory of your repo, create a folder named `.github`.
- Create a file named `README.md` in this folder.
- Save the relative path of the file you want to use as the repo README in `.github/README.md`.
This causes `README.md` to be interpreted as a symbolic link (symlink) file.
Example:
- This repo has files named `README.md` and `cmod-readme.md` in its root directory. Normally the former would be used as the README shown on the repo's main page, but instead the latter is used.
- The repo contains a `.github/README.md` file, which contains the relative path to `cmod-readme.md`, i.e., `../cmod-readme.md`.
The fact that GitHub will follow symlinks when locating a repo's README doesn't seem to be documented, although the `.github` folder is mentioned on this page in GitHub's docs:
If you put your README file in your repository's root, `docs`, or hidden `.github` directory, GitHub will recognize and automatically surface your README to repository visitors.
It's also interesting that (based on the example repo linked above) GitHub apparently prioritizes the `README.md` file in `.github` over a file of the same name in the repository's root.
Problem
Because of how Eclipse and EGit organize files and directories, I have my README.md file not in the root directory of my git repository but one folder deeper. How can I tell github to show `some_folder/README.md` as project's readme?