设置本地 Git 文档存储库

项目
12/21/2023

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

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

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

重要

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

概述

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

Screenshot showing the GitHub workflow for information flowing between the upstream, origin, and local clone.

确定存储库

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

如果不确定文章所在的存储库，请使用 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 并登录。
在 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
```

后续步骤

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