设置本地 Git 文档存储库

项目
12/21/2023

本文介绍在本地计算机上设置 Git 存储库的步骤，旨在为 Microsoft 文档提供帮助。参与者可以使用本地克隆的存储库来添加新项目，对现有文章进行主要编辑或更改图片。

运行如下一次性设置活动即可开始参与其中：

确定相应的存储库。
在 GitHub 帐户中创建存储库分支。
为克隆文件选择一个本地文件夹。
将存储库克隆到本地计算机。
配置上游远程值。

重要

如果要进行次要更改，无需完成本文中的相关步骤。请参阅“在浏览器中编辑”，了解如何在不安装任何工具的情况下快速编辑。

概述

要为参与编辑 Microsoft Learn 上的文档，可以通过克隆相应的文档存储库在本地创建和编辑 Markdown 文件。 Microsoft 要求在自己的 GitHub 帐户创建相应的存储库分支，以便具有读/写权限来存储建议的更改。然后，使用拉取请求 (PR) 将更改合并到只读的中央共享存储库。

显示 GitHub 工作流的屏幕截图，其中显示了上游、源和本地克隆之间流动的信息。

确定存储库

Microsoft Learn 中托管的文档位于 GitHub 的多个不同存储库中。

如果不确定文章所在的存储库，请使用 Web 浏览器访问该文章。选择文章右上方的“编辑”链接（铅笔图标）。
此操作会转到 GitHub 上的源文件。存储库名称显示在页面的左上角。

以下列出了一些可进行公共参与的常用存储库：
- Microsoft Learn 社区内容 https://github.com/MicrosoftDocs/community-content/
- Azure 文档 https://github.com/MicrosoftDocs/azure-docs
- SQL Server 文档 https://github.com/MicrosoftDocs/sql-docs
- Visual Studio 文档 https://github.com/MicrosoftDocs/visualstudio-docs
- .NET 文档 https://github.com/dotnet/docs
- Azure .NET SDK 文档 https://github.com/azure/azure-docs-sdk-dotnet
- ConfigMgr 文档 https://github.com/MicrosoftDocs/SCCMdocs

为存储库创建分支

确定正确的存储库后，下一步是在自己的 GitHub 帐户创建存储库的分支。

创建存储库分支是指在 GitHub 帐户中创建其副本。由于所有 Microsoft 文档存储库均提供只读访问权限，但分支提供写入访问权限以进行更改，因此需创建个人分支。个人分支允许将 PR 从自己的分支提交到 Microsoft 存储库。

在主存储库的 GitHub 页面，选择右上角的“创建分支”按钮。
在“创建新分支”屏幕上，确保将“所有者”设置为自己的用户名，并勾选“仅复制主分支”。（可选）更改“存储库名称”和“说明”字段。

克隆存储库

克隆是指在本地计算机上创建存储库的副本。

警告

请勿将本地存储库克隆到 OneDrive 同步的文件夹。选择将存储库克隆到的文件夹时，请勿选择与 OneDrive 同步的文件夹（例如“文档”文件夹）。将更改合并回主分支时，OneDrive 可能会导致意外合并冲突。因此，最好在 C:\ 驱动器上创建较短的文件路径（例如 C:\GitHub）。
基于 Windows 的 Git：启用较长的路径名称。默认情况下，Git for Windows 禁用对较长文件路径的支持，这会阻止克隆目标路径长度超过 255 个字符的任何文件。通过以管理员身份运行下列命令来启用较长的文件路径，从而避免此问题：
git config --global core.longpaths true

在本地计算机上创建 GitHub 文件夹。例如，C:\GitHub。（请勿克隆到 OneDrive 同步的文件夹。
在浏览器中，转到 GitHub.com 并登录。
在 GitHub 中右上角，从配置文件下拉列表中选择“你的存储库”。此时会显示存储库页面，其中包含已创建的分支存储库的列表。
选择要克隆的存储库。此时会显示分支存储库页面。

请确保位于你的分支存储库页面上，而不是生产存储库的页面。可以通过检查 URL 来确认正在使用的存储库是否为分支：它应显示 GitHub 用户名，而不是 Microsoft 组织（例如，显示 https://github.com/nancydavolio/azure-docs，而非 https://github.com/MicrosoftDocs/azure-docs）。此外，可以在左上角会看到你的名称，还可以看到一条说明，上面写着“forked from”后跟主存储库的名称。
选择页面顶部的<>代码选项卡。
在右侧的“Code”下拉列表中，复制“HTTPS”选项下的 URL。

重要

通过 GitHub UI 复制了克隆 URL。其余步骤应在 VS Code 终端中执行。

通过 Visual Studio Code 克隆

打开 Visual Studio Code。
在顶部导航菜单中，选择“视图”，然后选择“终端”。终端视图将显示在 Visual Studio Code 屏幕底部。
在“终端”视图中，运行以下命令，将目录 (cd) 更改为在“克隆存储库”部分中的步骤 1 中为驱动器上的存储库创建的 GitHub 文件夹。

示例：
```
 cd C:\GitHub
```
如果遇到错误，可能需要逐个更改文件夹的目录。

运行下列命令以克隆存储库：

git clone <paste the clone URL you copied via the GitHub UI>

例如：

git clone https://github.com/nancydavolio/azure-docs.git

系统提示通过浏览器进行身份验证时，请选择“使用浏览器登录”按钮并完成此过程。请务必下载最新版本的 Git，该版本支持通过浏览器功能进行身份验证。如果选择使用 GitHub 个人访问令牌，可按照以下说明生成：创建个人访问令牌。

克隆命令将分支的存储库文件下载到在步骤 3 中选择的新文件夹中。在当前文件夹中创建新的文件夹。这可能需要花费几分钟，具体取决于存储库大小。可浏览文件夹，查看完成后的结构。

设置远程

克隆存储库后，为名为“上游”的主存储库设置只读的远程连接。 “Remotes”是远程存储库的别名。 “Origin”是指分支存储库，“upstream”是指生产存储库。运行 clone 命令时，Git 会自动创建 origin 远程。利用此上游 URL，使本地存储库与其他人所做的最新更改保持同步。

在“Git Bash”或“VS Code 终端”中，运行以下命令。

将目录 (cd) 更改为命令 clone 创建的存储库文件夹。例如：
```
cd repo-name
```
运行以下命令，添加指向生产存储库的名为 upstream 远程存储库。例如，upstream 存储库 URL 为 https://github.com/MicrosoftDocs/azure-docs.git 而非 https://github.com/nancydavolio/azure-docs.git。
```
git remote add upstream <the clone URL of the main repo>
```
例如：
```
git remote add upstream https://github.com/MicrosoftDocs/azure-docs.git
```

运行以下命令，确保远程存储库正确：

git remote -v

输出示例：

origin  https://github.com/nancydavolio/azure-docs.git (fetch)
origin  https://github.com/nancydavolio/azure-docs.git (push)
upstream        https://github.com/MicrosoftDocs/azure-docs.git (fetch)
upstream        https://github.com/MicrosoftDocs/azure-docs.git (push)

如果出现错误，请删除远程存储库并重复上述步骤重新添加。要删除 upstream，请运行以下命令：
```
git remote remove upstream
```

后续步骤

设置本地克隆后，即可进行重大更改。

通过