在GitHub

Question

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

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

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

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

Answer 1

GitHub looks for README files in a few places：

  

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

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

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

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

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

  符号链接仅适用于Windows Vista或更高版本的NTFS文件系统，创建它们需要special rights or Developer Mode。它们是not supported by Git on Windows out of the box。

  在您的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使用的任何其他位置（存储库根目录或存储库根目录中的README文件夹）中没有真正的docs/文件。

克隆存储库的Windows用户将无法自动获取符号链接。如果他们希望有这种行为，他们应该用一个特殊的参数克隆：

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

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