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

Question

使用 GitHub 的基于 Web 的界面，我无法弄清楚如何为项目的 README 文件指定备用路径/文件名。

创建新的 README 时，Web 界面确实让我可以选择使用我想要的任意路径或文件名，但我选择的文件不会用作项目级 README。我希望它在用户访问项目页面时显示。

在具有所有此类/README.md项目的所有此类 README 文件的模块或扩展（例如 Magento 1 模块）的项目的上下文中，它们将在最终合并中全部被覆盖，因此应使用备用路径或文件名（例如/docs/projectname/README.md或/projectname.md）。

如何以将该文件指定为默认自述文件的方式执行此操作？

Answer 1

GitHub在几个地方寻找README文件：

如果您将 README 文件放在存储库的根目录、docs或隐藏.github目录中，GitHub 将识别并自动向存储库访问者显示您的 README。

如果你想为你的项目级别使用另一个文件，README我建议创建一个隐藏.github/目录并用 GitHub 期望的名称符号链接你的文件。

• 在 Linux 或 macOS 上，这应该相当简单：

  # From your repository root
  mkdir .github
  cd .github
  ln -s ../docs/projectname/some-README.md README.md
  

• 在 Windows 上，事情有点棘手。

  符号链接仅在 Windows Vista 或更高版本的 NTFS 文件系统上可用，创建它们需要特殊权限或开发人员模式。Windows 上的 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。您可能希望确保READMEGitHub 使用的任何其他位置（存储库根目录或存储库根目录中的docs/文件夹）中都没有真实文件。

克隆存储库的 Windows 用户不会自动获得符号链接。如果他们希望有这种行为，他们应该使用特殊参数进行克隆：

git clone -c core.symlinks=true <repo-url>

¹可以向mklink非管理员用户授予权限，但以管理员身份运行可能是最简单的解决方案。