GitHub在几个地方寻找README文件:
如果您将README文件放在存储库的根目录、docs目录或隐藏的.github目录中,GitHub将会识别并自动展示给访问存储库的用户。
如果您想使用另一个文件作为项目级别的README,我建议您创建一个隐藏的.github/目录,并将文件链接到那里,并使用GitHub期望的名称。
在Linux或macOS上,这应该相对简单:
从您的存储库根目录开始
mkdir .github
cd .github
ln -s ../docs/projectname/some-README.md README.md
在Windows上,情况要复杂一些。
符号链接仅适用于Windows Vista或更高版本的NTFS文件系统,并且创建它们需要特殊权限或开发者模式。它们在Git上默认情况下不受支持。
在您的Git shell中,在存储库的根目录中,为当前存储库启用符号链接:
git config core.symlinks true
现在以管理员身份¹运行cmd.exe并cd到存储库根目录。创建您的符号链接:
mkdir .github
cd .github
mklink README.md ..\docs\projectname\some-README.md
请注意,此处链接的名称在真实文件的名称之前,与上述Linux和macOS说明相反。现在可以关闭cmd.exe并返回到Git Bash。
现在提交
.github/README.md
并推送到 GitHub。您可能希望确保在 GitHub 使用的其他位置(存储库根目录或存储库根目录中的
docs/
文件夹)中没有真正的
README
文件。
克隆存储库的 Windows 用户不会自动获得符号链接。如果他们希望具有该行为,他们应该使用特殊参数进行克隆:
git clone -c core.symlinks=true <repo-url>
可以将mklink权限授予非管理员用户,但以管理员身份运行可能是最简单的解决方案。