mirror of
https://github.com/LCTT/TranslateProject.git
synced 2024-12-23 21:20:42 +08:00
265 lines
11 KiB
Markdown
265 lines
11 KiB
Markdown
[#]: subject: "7 Git tips for technical writers"
|
||
[#]: via: "https://opensource.com/article/22/11/git-tips-technical-writers"
|
||
[#]: author: "Maximilian Kolb https://opensource.com/users/kolb"
|
||
[#]: collector: "lkxed"
|
||
[#]: translator: "ChatGPT"
|
||
[#]: reviewer: "wxy"
|
||
[#]: publisher: "wxy"
|
||
[#]: url: "https://linux.cn/article-16044-1.html"
|
||
|
||
专为技术写作人员提供的 7 条 Git 技巧
|
||
=====
|
||
|
||
![][0]
|
||
|
||
> 跟随这个演示来了解我如何使用 Git 为 Foreman 编写文档。
|
||
|
||
作为 [ATIX][1] 的技术作家，我的任务包括为 [Foreman][2] 创建和维护存放在 [github.com/theforeman/foreman-documentation][3] 的文档。Git 帮助我跟踪内容的版本，并与开源社区进行协作。它是我存储工作成果、共享和讨论改进的重要工具。我主要使用的工具包括浏览器、用 OpenSSH 连接 Foreman 实例、用 [Vim][4] 编辑源文件，以及使用 Git 进行版本控制。
|
||
|
||
本文重点介绍在开始使用 Git 和为 Foreman 文档做贡献时经常遇到的挑战。适用于中级 Git 用户。
|
||
|
||
### 先决条件
|
||
|
||
- 你已在系统上安装和配置了 Git。你至少需要设置用户名和电子邮件地址。
|
||
- 你在 [github.com][5] 上拥有一个帐户。GitHub 本身并不是一个开源项目，但它是许多开源 Git 存储库的托管站点（包括 Foreman 的文档）。
|
||
- 你已将 [foreman-documentation][3] 存储库复刻到你自己的账户或组织（例如，`github.com/<My_User_Account>/foreman-documentation`，这里 `<My_User_Account>` 是你的 GitHub 用户名）。有关更多信息，请参阅 Kedar Vijay Kulkarni 的 [Kedar Vijay Kulkarni 的 Git 逐步指南][6]。
|
||
- 你已将你的 SSH 公钥添加到 GitHub。这是将你的更改推送到 GitHub 所必需的。有关更多信息，请参阅 Nicole C. Baratta 的《[GitHub 简单指引][7]》。
|
||
|
||
### 对 Foreman 文档做出贡献
|
||
|
||
Foreman 是一个开源项目，依靠社区的贡献而发展壮大。该项目欢迎所有人的参与，并且只有一些要求才能做出有意义的贡献。这些要求和惯例在 [README.md][8] 和 [CONTRIBUTING.md][9] 文件中有详细记录。
|
||
|
||
以下是在处理 Foreman 文档时最常见的一些任务。
|
||
|
||
#### 我想开始贡献 Foreman 文档
|
||
|
||
1、从 github.com 克隆存储库：
|
||
|
||
```
|
||
$ git clone git@github.com:theforeman/foreman-documentation.git
|
||
$ cd foreman-documentation/
|
||
```
|
||
|
||
2、重命名远程存储库：
|
||
|
||
```
|
||
$ git remote rename origin upstream
|
||
```
|
||
|
||
3、可选：确保你的本地主分支跟踪 theforeman 组织的 `foreman-documentation` 存储库的 `master` 分支：
|
||
|
||
```
|
||
$ git status
|
||
```
|
||
|
||
这将自动将你置于默认分支（本例中为 `master`）的最新提交上。
|
||
|
||
4、如果你的账户或组织中尚未有该存储库的 <ruby>复刻<rt>Fork</rt></ruby>，请创建一个。前往 [github.com/theforeman/foreman-documentation][3] 并点击 “<ruby>复刻<rt>Fork</rt></ruby>” 按钮。
|
||
|
||
5、将你的复刻添加到你的存储库中：
|
||
|
||
```
|
||
$ git remote add github git@github.com:<My_User_Account>/foreman-documentation.git
|
||
```
|
||
|
||
你的本地存储库现在有两个远程存储库：`upstream` 和 `github`。
|
||
|
||
#### 我想扩展 Foreman 文档
|
||
|
||
对于简单的更改，比如修正拼写错误，你可以直接创建一个拉取请求（PR）。
|
||
|
||
1、创建一个分支，例如 `fix_spelling`。`git switch` 命令用于切换当前所在的分支，`-c` 参数用于创建分支：
|
||
|
||
```
|
||
$ git switch -c fix_spelling
|
||
```
|
||
|
||
2、进行你的更改。
|
||
|
||
3、添加你的更改并进行提交：
|
||
|
||
```
|
||
$ git add guides/common/modules/abc.adoc
|
||
$ git commit -m "Fix spelling of existing"
|
||
```
|
||
|
||
良好的 Git 提交消息的重要性无需再强调。提交消息告诉贡献者你做了哪些工作，因为它与代码库的其余部分一起保存，所以它在查看代码时起到历史注释的作用，帮助了解代码的演化过程。有关优秀的 Git 提交消息的更多信息，请参阅由 cbeams 撰写的 《[创建完美的 Git 提交信息的 7 条规则][10]》。
|
||
|
||
4、可选但建议的操作：查看并验证与默认分支的差异。`foreman-documentation` 的默认分支称为 `master`，但其他项目可能有不同的命名（例如 `main`、`dev` 或 `devel`）。
|
||
|
||
```
|
||
$ git diff master
|
||
```
|
||
|
||
5、将分支推送到 GitHub。这将发布你的更改到你的代码库副本：
|
||
|
||
```
|
||
$ git push --set-upstream github fix_spelling
|
||
```
|
||
|
||
6、点击终端中 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
|
||
```
|
||
|
||
7、在解释中说明社区*为什么*应该接受你的更改。对于修正拼写错误等简单 PR，这并不是必需的，但对于重大更改则很重要。
|
||
|
||
#### 我想将我的分支变基到 master
|
||
|
||
1、确保你的本地 `master` 分支跟踪的是 [github.com/theforeman/foreman-documentation][3] 的 `master` 分支，而不是你自己命名空间下的 `foreman-documentation`：
|
||
|
||
```
|
||
$ git switch master
|
||
```
|
||
|
||
此时应该显示 `Your branch is up to date with 'upstream/master'`，其中 `upstream` 是指向 `github.com/theforeman/foreman-documentation` 的远程存储库的名称。你可以通过运行 `git remote -v` 来查看远程存储库设置情况。
|
||
|
||
2、从远程获取可能的更改。`git fetch` 命令会从远程下载被跟踪的分支，并且使用 `--all` 选项可以同时更新所有分支。在使用其他分支时这是必要的。`--prune` 选项会删除对已不存在的分支的引用。
|
||
|
||
```
|
||
$ git fetch --all --prune
|
||
```
|
||
|
||
3、将可能的更改从 `upstream/master` 拉取到你的本地 `master` 分支。`git pull` 命令将跟踪的分支上的提交复制到当前分支。这用于将你的本地 `master` 分支“更新”为远程（在本例中为 GitHub）`master` 分支的最新状态。
|
||
|
||
```
|
||
$ git pull
|
||
```
|
||
|
||
4、将你的分支 <ruby>变基<rt>rebase</rt></ruby> 到 `master`。
|
||
|
||
```
|
||
$ git switch my_branch
|
||
$ git rebase -i master
|
||
```
|
||
|
||
#### 我在 master 分支上意外地提交了代码
|
||
|
||
1、创建一个分支来保存你的工作：
|
||
|
||
```
|
||
$ git switch -c my_feature
|
||
```
|
||
|
||
2、切换回 `master` 分支：
|
||
|
||
```
|
||
$ git switch master
|
||
```
|
||
|
||
3、回退 `master` 分支上的最后一次提交：
|
||
|
||
```
|
||
$ git reset --soft HEAD~1
|
||
```
|
||
|
||
4、切换回 `my_feature` 分支并继续工作：
|
||
|
||
```
|
||
$ git switch my_feature
|
||
```
|
||
|
||
#### 我想修改我的提交消息
|
||
|
||
1、如果你的分支只有一次提交，可以使用 `git amend` 来修改你的最后一次提交：
|
||
|
||
```
|
||
$ git commit --amend
|
||
```
|
||
|
||
这假设你没有将其他文件添加到暂存区（即，没有运行过 `git add My_File`，并且没有进行提交）。
|
||
|
||
2、使用 `--force` 选项将你的 “更改” 推送到 GitHub，因为 Git 提交消息是你现有提交的一部分，所以你正在更改分支上的历史记录：
|
||
|
||
```
|
||
$ git push --force
|
||
```
|
||
|
||
#### 我想重新整理单个分支上的多个更改
|
||
|
||
1、可选但强烈推荐：从 GitHub 获取更改。
|
||
|
||
```
|
||
$ git switch master
|
||
$ git fetch
|
||
$ git pull
|
||
```
|
||
|
||
这确保你将其他更改按照它们被合并到 `master` 中的顺序直接合并到你的分支中。
|
||
|
||
2、若要重新整理你的工作，请对你的分支进行变基并根据需要进行更改。对于将分支变基到 `master`，这意味着你需要更改你的分支上第一个提交的父提交：
|
||
|
||
```
|
||
$ git rebase --interactive master
|
||
```
|
||
|
||
使用你喜欢的编辑器打开变基交互界面，将第一个单词 `pick` 替换为你要修改的提交。
|
||
|
||
- 使用 `e` 来对你的提交进行实际更改。这会中断你的变基操作！
|
||
- 使用 `f` 将一个提交与其父提交合并。
|
||
- 使用 `d` 完全删除一个提交。
|
||
- 移动行以改变你更改的顺序。
|
||
|
||
成功进行变基后，你自己的提交将位于 `master` 上最后一个提交的顶部。
|
||
|
||
#### 我想从其他分支复制一个提交
|
||
|
||
1、从稳定分支（例如名为 `3.3` 的分支）获取提交的 ID，请使用 `-n` 选项限制提交数量：
|
||
|
||
```
|
||
$ git log -n 5 3.3
|
||
```
|
||
|
||
2、通过挑选提交来复制更改到你的分支。`-x` 选项将提交的 ID 添加到你的提交消息中。这仅建议在从稳定分支挑选提交时使用：
|
||
|
||
```
|
||
$ git switch My_Branch
|
||
$ git cherry-pick -x Commit_ID
|
||
```
|
||
|
||
### 更多技巧
|
||
|
||
在 ATIX，我们运行一个 [GitLab][11] 实例，用于内部共享代码、协作以及自动化测试和构建。对于围绕 Foreman 生态系统的开源社区，我们依赖于 GitHub。
|
||
|
||
我建议你始终将名为 `origin` 的远程指向你的*内部的*版本控制系统。这样做可以防止在纯粹凭记忆进行 `git push` 时向外部服务泄露信息。
|
||
|
||
此外，我建议使用固定的命名方案来命名远程。我总是将指向自己的 GitLab 实例的远程命名为 `origin`，将指向开源项目的远程命名为 `upstream`，将指向我在 Github 上的复刻的远程命名为 `github`。
|
||
|
||
对于 `foreman-documentation`，该存储库具有相对较平的历史记录。当处理更复杂结构时，我倾向于以非常可视化的方式思考 Git 存储库，其中节点（提交）指向线上的节点（分支），这些分支可以交织在一起。图形化工具如 `gitk` 或 [Git Cola][12] 可以帮助可视化你的 Git 历史记录。一旦你完全掌握了 Git 的工作原理，如果你更喜欢命令行，可以使用别名。
|
||
|
||
在进行具有大量预期合并冲突的大型变基之前，我建议创建一个“备份”分支，以便你可以快速查看差异。请注意，要永久删除提交是相当困难的，因此在进行重大更改之前，请在本地 Git 存储库中进行测试。
|
||
|
||
### Git 对技术文档编写者的帮助
|
||
|
||
Git 对技术文档编写者来说是一个巨大的帮助。不仅可以使用 Git 对文档进行版本控制，还可以与他人积极地进行协作。
|
||
|
||
*（题图：MJ/1fb1dd43-e460-4e76-9ff6-b6ef76570f7e）*
|
||
|
||
--------------------------------------------------------------------------------
|
||
|
||
via: https://opensource.com/article/22/11/git-tips-technical-writers
|
||
|
||
作者：[Maximilian Kolb][a]
|
||
选题：[lkxed][b]
|
||
译者：ChatGPT
|
||
校对：[wxy](https://github.com/wxy)
|
||
|
||
本文由 [LCTT](https://github.com/LCTT/TranslateProject) 原创编译，[Linux中国](https://linux.cn/) 荣誉推出
|
||
|
||
[a]: https://opensource.com/users/kolb
|
||
[b]: https://github.com/lkxed
|
||
[1]: https://atix.de/en/
|
||
[2]: https://opensource.com/article/17/8/system-management-foreman
|
||
[3]: https://github.com/theforeman/foreman-documentation
|
||
[4]: https://opensource.com/resources/what-vim
|
||
[5]: https://github.com/
|
||
[6]: https://opensource.com/article/18/1/step-step-guide-git
|
||
[7]: https://opensource.com/life/15/11/short-introduction-github
|
||
[8]: https://github.com/theforeman/foreman-documentation/blob/master/guides/README.md#contribution-guidelines
|
||
[9]: https://github.com/theforeman/foreman-documentation/blob/master/CONTRIBUTING.md#contributing-to-foreman-documentation
|
||
[10]: https://cbea.ms/git-commit/#seven-rules
|
||
[11]: https://about.gitlab.com/
|
||
[12]: https://opensource.com/article/20/3/git-cola
|
||
[0]: https://img.linux.net.cn/data/attachment/album/202307/29/082043e587yilezk45ayin.jpg |