在GitHub上指定备用项目级README.md

12

在使用 GitHub 的基于 Web 的界面时,我无法找到指定项目 README 文件的替代路径/文件名的方法。

创建新的 README 文件时,Web 界面确实提供了使用任意路径或文件名的选项,但我选择的文件并未用作项目级别的 README。我希望它在用户访问项目页面时能够显示。

对于作为模块或扩展的项目(例如 Magento 1 模块),将所有这些 README 文件放在所有这些项目的 /README.md 下会在最终合并中将它们全部覆盖,因此应该使用替代路径或文件名(例如/docs/projectname/README.md/projectname.md)。

如何以一种指定该文件为默认 README 的方式完成这项工作?

1个回答

27
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权限授予非管理员用户,但以管理员身份运行可能是最简单的解决方案。

@nuno,你能提供你最近编辑的参考资料吗?我在快速搜索中找不到任何参考资料,我很想撤销这个编辑。 - undefined
嗯,这是参考链接,但我刚在Windows 11上测试过,情况并非如此。已修复。 - undefined
1
不太确定我会信任HowToGeek作为参考。官方的微软文档会更理想。 - undefined
现在我非常确定没有人应该这样做 - undefined

网页内容由stack overflow 提供, 点击上面的
可以查看英文原文,
原文链接