Microsoft Learn 文档的 Git 和 GitHub 基础知识

概述

作为 Microsoft Learn 文档的参与者，你将与多个工具和流程进行交互。 你将与其他参与者并行处理同一项目，可能是完全相同的内容，甚至在同一时间。 这一切都可以通过 Git 和 GitHub 软件实现。

Git 是一个开源版本控制系统。 它通过存储库中文件的分布式版本控制来促进这种类型的项目协作。 实质上，Git 可以为给定的存储库整合多个参与者持续完成的工作流。

GitHub 是 Git 存储库基于 Web 的托管服务，例如用于存储 Microsoft Learn 内容的托管服务。 对于任何项目，GitHub 托管主存储库，其中，参与者可为自己的工作创建副本。

本文定义了属于 Microsoft Learn 工作流的关键术语。 此外，它还概述了 Git 和 GitHub 存储库，并解释了如何为 Microsoft 技术文档组织内容。

分支

分支分隔工作流（通常称为版本）。 始终提供发布内容并将范围限定为特定分支。

将相关更改隔离到特定的分支中，可独立地控制和引入这些更改。 实际上，根据所执行的工作类型，你可以很容易地实现在存储库中使用多个工作分支。 同时使用多个分支很常见，每一项工作都代表一个不同的项目。

所有存储库均包含一个默认分支（通常名为“main”）以及一个或多个正在进行的分支（我们称之为”工作分支“），而这些分支尚未集成到默认分支中。 默认分支充当项目的当前版本和“单一事实来源”。 它是创建存储库中其他所有分支所依据的父级。

每次要引入一组新的在逻辑上有关联的更改时，最佳做法是创建一个工作分支，用于管理更改。 不建议直接对默认分支进行更改。

创建分支

在表示主 GitHub 存储库的副本时，此术语通常会用作名词。 实际上，分支只是另一个存储库。 但是，从某种意义上来说，GitHub 维护至主/父存储库的连接。 此术语有时会用作动词，如“必须首先为存储库创建分支”。

Git

如果熟悉集中式版本控制系统（如 Team Foundation Server、SharePoint 或 Visual SourceSafe），则会注意到，Git 有一个用于支持其分布式模型的特殊参与工作流程和术语。 例如，没有通常与签出/签入操作相关联的文件锁定。 相反，Git 关心的是更精细粒度级别的更改，以逐字节比较文件。

Git 还使用分层结构来存储和管理项目的内容：

• 存储库 (Repository)：英文缩写为“repo”，它是最大的存储单元。 存储库包括一个或多个分支。
• 分支：一个存储单元，包含构成项目内容集的文件和文件夹。 有关分支的详细信息，请参阅本文的分支部分。

参与者与 Git 进行交互，更新和处理本地和 GitHub 级别的存储库：

• 在本地，通过 Git Bash 控制台等工具，该工具支持用于管理本地存储库并与 GitHub 存储库进行通信的 Git 命令。
• 通过 www.github.com 集成 Git 来管理流回主存储库的参与协调。

GitHub

注意

尽管文档指南基于 GitHub 的使用而制定，但有些团队使用 Visual Studio Team Service 来托管 Git 存储库。 Visual Studio 团队资源管理器客户端提供用于与 Team Services 存储库进行交互的 GUI，作为通过命令行使用 Git 命令的替代方法。
此外，根据在 GitHub 中托管 Azure 服务内容的多年经验，以下许多指南都被开发为最佳做法。 某些 Microsoft Learn 存储库可能需要它们。

所有工作流在 GitHub 级别开始和结束，期间存储任何文档项目的主存储库。 参与者为自行使用而创建的副本将分散在多台计算机中。 这些副本将最终协调回项目的主 GitHub 存储库。

目录组织

项目的默认分支会用作项目的当前内容版本。 默认分支（以及从默认分支创建的分支）中的内容与相应 Microsoft Learn 页面上文章的组织大体一致。 子目录可用于分离文章（如服务）、媒体内容（如图像文件）和“包括”文件（使内容可重复使用）。

文章子目录

通常情况下，可在存储库的根目录处找到主要的 articles 目录。 articles 目录包含了一组子目录。子目录中的文章格式为使用 .md 扩展名的 Markdown 文件。 一些支持多项服务的存储库（如 Azure-Docs 存储库）使用通用 /articles 子目录。 另一些存储库可能会使用服务专用名称，如使用 /IntuneDocs 的 IntuneDocs 存储库。

在此目录的根目录中，可以找到与整体服务或产品相关的一般性文章。 通常情况下，接下来可以找到其他系列的子目录，这些子目录与功能/服务或常见方案相匹配。 例如，Azure“虚拟机”文章在 /virtual-machines 子目录中，Intune“了解与探索”文章在 /understand-explore 子目录中。

媒体子目录

每个文章目录均包含对应媒体文件的 /media 子目录。 媒体文件包含引用图像的文章所使用的图像。

包括子目录

只要在两个或多个文章间有共享的可重用内容，就可将其放入 articles 主目录的 /includes 子目录中。 在使用包含文件的 Markdown 文件中，相应的“include”Markdown 扩展名放置在需要引用包含文件的位置。

有关其他指南，请参阅 Markdown 引用：Include。

Markdown 文档模板

为方便起见，每个存储库的子目录通常包含名为 template.md 的 Markdown 模板文件。 如果需要创建新文章（用于提交到存储库），可使用此模板文件作为“起始文件”。 文件包含：

• 文件顶部的元数据标头，由 2 个 3 条连字符分隔。 它包含用于跟踪文章相关信息的各种标记。 文章元数据支持某些功能，如作者属性、参与者属性、痕迹导航和文章描述。 它还包括 SEO 优化和报告流程，Microsoft 用其来评估内容表现。 因此，元数据非常重要！
• 元数据部分介绍各种元数据标记和值。 如果不确定对元数据部分使用哪些值，可以将其留空，或使用前导井号标签 (#) 进行注释，然后由存储库拉取请求的审阅者审阅/完成它们。
• 对文章元素进行格式设置的各种 Markdown 使用示例。
• 常规 Markdown 扩展名使用说明，可用于各种警报类型。
• 使用 iframe 的嵌入视频示例。
• Microsoft 技术文档扩展的一般性使用说明，可用于特殊控件（如按钮和选择器）。

源

此术语是分配给本地存储库与在其中进行克隆的源存储库之间的连接的名称。 在 Microsoft Learn 工作流中，源表示与分支的连接。 此术语有时会用作源存储库自身的一个名字对象，如“请务必将更改推送到源。”

拉取请求

拉取请求 (PR) 是指要求内容所有者将更改拉取到官方源的请求。 PR 通过请求将工作分支的更改（也称为提交）拉取并合并到其他分支，从而实现 GitHub 的协作模型。 大多数情况下，其他分支就是主存储库中的默认分支。

PR 还可作为一种机制，在将更改合并到默认分支之前，为贡献者提供来自 Microsoft Learn 验证流程和 PR 审核员的反馈，以解决问题或疑问。

远程

远程是指与远程存储库的已命名连接，例如“源”或“上游”远程。 Git 称之为“远程源”，因为可用于引用托管在另一台计算机上的存储库。 在 Microsoft Learn 工作流中，远程始终是一个 GitHub 存储库。

上游

与源远程一样，上游是指与其他存储库的已命名连接。 在 Microsoft Learn 工作流中，上游表示本地存储库与在其中创建分支的主存储库之间的连接。 此术语有时会用作上游存储库自身的一个名字对象，如“请务必从上游拉取最新更改。”

了解详细信息

如果不熟悉 Git 或 GitHub，可通过这些资源了解、提高工作效率或者回答问题。

Git 源控制资源

• Pro Git 电子书 (web)：采用 HTML 格式的全面 Git 引用。
• Pro Git 电子书 (PDF)：与前面的链接相同，采用 PDF 形式。
• 从 Codecademy 学习 Git 课程
• 从 Pluralsight 上的 Code School 尝试学习 Git 课程

GitHub 资源

• GitHub Hello World 快速入门练习：使用 GitHub 学习 Git 基础知识的在线教程。
• GitHub 指南：GitHub 文档的主页。
• GitHub 学习资源：其他有用的 GitHub 资源。
• 词汇表：便捷的 Git 和 GitHub 术语词汇表。
• GitHub 学生开发者包：为学生提供免费访问最佳开发人员工具的权限。

常见问题

什么是 Git？

当有许多人一起编写计算机代码时，Git 可帮助跟踪更改。 它就像代码的时间机器，让你可以看到进行了哪些更改并在需要时回退。

为何要使用 Git？

它非常适合团队合作。 通过 Git，很多人可以轻松处理同一个项目，而不会互相干扰。 它还有助于轻松修复错误。

Git 是如何工作的？

Git 存储项目代码的所有版本。 进行更改时，Git 会拍摄不同内容的照片（如快照）。 你可以同时创建不同的版本，而不会出现问题。

什么是 Git 中的分支？

分支类似于项目中的不同路径。 让用户在不改变主项目的情况下处理新的工作内容。 稍后，可以将这些更改重新引入主项目。

Git 中的提交是什么？

提交类似于保存点。 它是记录所做更改的一种方法。 每个提交都有一个唯一的 ID，以及有关已更改的内容的注释。

什么是 GitHub？

GitHub 是一个网站，可在其中存储 Git 项目。 这就像一个大中心，用于与他人共享和协作处理代码。 它还有助于跟踪谁更改了哪些内容。

GitHub 与 Git 有何不同？

Git 是用于跟踪更改的工具，而 GitHub 是存储项目并协同工作的地方。 GitHub 使用 Git 来提供服务。

GitHub 是否免费？

是的，每个人都可以看到项目。 但是对于私人项目（只有你和你的团队），则可能需要付费。 它们提供具有额外功能的不同计划。

GitHub 中的拉取请求是什么？

拉取请求类似于要求将更改放入主项目。 用户可以在添加更改之前查看和讨论这些更改。

GitHub 的安全性如何？

GitHub 十分注重安全性。 它们使用特殊代码和规则来确保只有合适的人员可以访问和更改代码。 还可以添加额外的安全层（例如双因素身份验证），以增加安全性。