技术文档撰写者的 7 个 Git 技巧

跟随这个演示，了解我如何使用 Git 为 Foreman 编写文档。

Person drinking a hat drink at the computer

图片来自

作为 ATIX 的技术文档撰写者，我的任务包括为 Foreman 创建和维护文档，文档位于 github.com/theforeman/foreman-documentation。 Git 帮助我跟踪内容版本，并与开源社区协作。它是存储我的工作成果、共享它以及讨论改进的组成部分。我的主要工具包括浏览器、用于连接到 Foreman 实例的 OpenSSH、用于编辑源文件的 Vim 以及用于版本控制内容的 Git。

本文重点介绍使用 Git 并为 Foreman 文档做出贡献时遇到的常见挑战。这适用于中级 Git 用户。

先决条件

您已在您的系统上安装并配置了 Git。您必须至少设置您的用户名和电子邮件地址。
您在 github.com 上拥有一个帐户。 GitHub 本身不是一个开源项目，但它是许多开源 Git 存储库的存储站点（包括 Foreman 的文档。）
您已将 foreman-documentation 存储库 fork 到您自己的帐户或组织中（例如，github.com/_My_User_Account_/foreman-documentation。有关更多信息，请参阅 Kedar Vijay Kulkarni 的Git 逐步指南。
您已将您的 SSH 公钥添加到 GitHub。这是将您的更改推送到 GitHub 所必需的。有关更多信息，请参阅 Nicole C. Baratta 的 GitHub 简短介绍。

为 Foreman 文档做贡献

Foreman 是一个开源项目，并在社区贡献的基础上蓬勃发展。该项目欢迎所有人，并且只有少数要求才能做出有意义的贡献。要求和约定记录在 README.md 和 CONTRIBUTING.md 文件中。

以下是处理 Foreman 文档时最常见的任务。

我想开始处理 Foreman 文档

从 github.com 克隆存储库

$ git clone git@github.com:theforeman/foreman-documentation.git
$ cd foreman-documentation/

重命名远程仓库
```
$ git remote rename origin upstream
```
可选：确保您的本地 master 分支正在跟踪来自 theforeman 组织的 foreman-documentation 存储库的 master 分支
```
$ git status
```
这会自动从默认分支的最新提交开始，在这种情况下是 master。
如果您自己的帐户或组织中还没有该存储库的 fork，请创建一个。

转到 github.com/theforeman/foreman-documentation 并单击 Fork。
将您的 fork 添加到您的存储库。
```
$ git remote add github git@github.com:_My_User_Account_/foreman-documentation.git
```
您的本地存储库现在有两个远程仓库：upstream 和 github。

我想扩展 Foreman 文档

对于简单的更改，例如修复拼写错误，您可以直接创建一个拉取请求 (PR)。

创建一个名为 fix_spelling 的分支。 git switch 命令更改当前检出的分支，-c 创建分支
```
$ git switch -c fix_spelling
```
进行更改。
添加更改并提交
```
$ git add guides/common/modules/abc.adoc
$ git commit -m "Fix spelling of existing"
```
我再怎么强调好的 Git 提交消息的重要性都不为过。提交消息告诉贡献者您做了什么，并且因为它与其余代码库一起保存，所以当有人回顾代码以确定其生命周期中发生的事情时，它就充当了历史脚注。有关优秀的 git 提交消息的更多信息，请参阅 cbeams 的优秀 Git 提交消息的七个规则。
可选但建议：查看并验证与默认分支的差异。 foreman-documentation 的默认分支称为 master，但其他项目可能会以不同的方式命名（例如，main、dev 或 devel。）
```
$ git diff master
```
将您的分支推送到 Github。这会将您的更改发布到您的代码库副本中。
```
$ git push --set-upstream github fix_spelling
```

单击 Git 在您的终端中提供的链接以创建拉取请求 (PR)。

remote: Create a pull request for 'fix_spelling' on Github by visiting:
remote:      https://github.com/_My_User_Account_/foreman-documentation/pull/new/fix_spelling

添加一个解释，说明为什么社区应该接受您的更改。对于简单的 PR（例如修复拼写错误）来说，这不是必需的，但对于重大更改来说，这很重要。

更多关于 Git 的信息

我想将我的分支 rebase 到 master。

确保您的本地 master 分支跟踪来自 github.com/theforeman/foreman-documentation 的 master 分支，而不是您自己的命名空间中的 foreman-documentation
```
$ git switch master
```
这应该显示 您的分支与 'upstream/master' 同步，其中 upstream 是您的远程存储库的名称，指向 github.com/theforeman/foreman-documentation。您可以通过运行 git remote -v 来查看您的远程仓库。
从您的远程仓库获取可能的更改。 git fetch 命令从您的远程仓库下载跟踪的分支，--all 选项同时更新所有分支。这在使用其他分支时是必需的。 --prune 选项删除对不再存在的分支的引用。
```
$ git fetch --all --prune
```
将可能的更改从 upstream/master 拉取到您的本地 master 分支中。 git pull 命令将您正在跟踪的分支中的提交复制到您当前的分支中。这用于将您的本地 master 分支“更新”到您的远程仓库（在本例中为 Github）中的 master 分支的最新状态。
```
$ git pull
```

将您的分支 rebase 到 "master"。

$ git switch my_branch
$ git rebase -i master

我不小心提交到了 master

创建一个分支以保存您的工作
```
$ git switch -c my_feature
```
切换回 master 分支
```
$ git switch master
```
删除 master 上的最后一次提交
```
$ git reset --soft HEAD~1
```
切换回 my_feature 分支并继续工作
```
$ git switch my_feature
```

我想重新措辞我的提交消息

如果您的分支上只有一个提交，请使用 git amend 来更改您的最后一次提交
```
$ git commit --amend
```
这假设您没有将任何其他文件添加到您的暂存区（也就是说，您没有运行 git add My_File 且没有提交它。）
使用 --force 选项将您的“更改”推送到 Github，因为 Git 提交消息是您现有提交的一部分，因此您正在更改分支上的历史记录。
```
$ git push --force
```

我想重组单个分支上的多个更改

可选但强烈建议：从 Github 获取更改。
```
$ git switch master
$ git fetch
$ git pull
```
这确保您直接将任何其他更改按合并到 master 的顺序合并到您的分支中。
要重构您的工作，请 rebase 您的分支并根据需要进行更改。 Rebase 到 master 意味着更改您的分支上的第一次提交的父提交
```
$ git rebase --interactive master
```
替换第一个单词 pick 以修改提交。
- 使用 e 对您的提交进行实际更改。这会中断您的 rebase！
- 使用 f 将提交与其父提交合并。
- 使用 d 将提交从您的分支中完全删除。
- 移动行以更改更改的顺序。
  
  成功 rebase 后，您自己的提交位于来自 master 的最后一次提交之上。

我想从另一个分支复制一个提交

从稳定分支（例如，名为 3.3 的分支）获取提交 ID，使用 -n 选项来限制提交的数量。
```
$ git log -n 5 3.3
```
通过将提交 cherry-pick 到您的分支来复制更改。 -x 选项将提交 ID 添加到您的提交消息。仅建议从稳定分支 cherry-pick 提交。
```
$ git switch My_Branch
$ git cherry-pick -x Commit_ID
```