6

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

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

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

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

4

1 回答 1

9

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

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

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

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

于 2018-04-23T12:59:05.257 回答