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

Question

使用 GitHub 的基于 Web 的界面，我不知道如何为项目的自述文件指定备用路径/文件名。

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

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

我怎样才能以将该文件指定为默认自述文件的方式执行此操作？

Answer 1

Git中心 looks for README files in a few places:

If you put your README file in your repository's root, docs, or hidden .github directory, GitHub will recognize and automatically surface your README to repository visitors.

如果你想为你的项目级别使用另一个文件 README 我建议创建一个隐藏的 .github/ 目录和 symlinking 你的文件在那里命名为 Git集线器预计。

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

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

在 Windows 上有点棘手。

符号 link 仅在 Windows Vista 或更高版本的 NTFS 文件系统上可用，创建它们需要 special rights or Developer Mode. They are not supported by Git on Windows out of the box.

在您的 Git shell 中，在您存储库的根目录中，为当前存储库启用 symlinks：
```
git config core.symlinks true
```
现在运行 cmd.exe 作为管理员¹ 和 cd 到存储库根目录。让你的 symlink:
```
mkdir .github
cd .github
mklink README.md ..\docs\projectname\some-README.md
```
请注意，link 的名称在之前实际文件的名称，与上面的 Linux 和 macOS 说明形成对比。您现在可以关闭 cmd.exe 并返回 Git Bash.

现在提交 .github/README.md 并推送到 GitHub。您可能需要确保在 GitHub 使用的任何其他位置（存储库根目录或存储库根目录中的 docs/ 文件夹中没有真正的 README 文件).

Windows 克隆存储库的用户不会自动获得 symlink。如果他们希望有这种行为，他们应该用一个特殊的参数克隆：

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

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

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

Specify alternate project-level README.md on GitHub

github

readme