From 1c61f953f7a14f82ee869206461e930211c5f612 Mon Sep 17 00:00:00 2001 From: Xingyu Wang Date: Sat, 29 Jul 2023 08:22:31 +0800 Subject: [PATCH] ATRP @wxy https://linux.cn/article-16044-1.html --- ...1 ⭐️⭐️ 7 Git tips for technical writers.md | 265 ++++++++++++++++++ ...1 ⭐️⭐️ 7 Git tips for technical writers.md | 131 --------- 2 files changed, 265 insertions(+), 131 deletions(-) create mode 100644 published/20221121.1 ⭐️⭐️ 7 Git tips for technical writers.md delete mode 100644 sources/tech/20221121.1 ⭐️⭐️ 7 Git tips for technical writers.md diff --git a/published/20221121.1 ⭐️⭐️ 7 Git tips for technical writers.md b/published/20221121.1 ⭐️⭐️ 7 Git tips for technical writers.md new file mode 100644 index 0000000000..e07bcc469e --- /dev/null +++ b/published/20221121.1 ⭐️⭐️ 7 Git tips for technical writers.md @@ -0,0 +1,265 @@ +[#]: 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//foreman-documentation`，这里 `` 是你的 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、如果你的账户或组织中尚未有该存储库的 复刻Fork，请创建一个。前往 [github.com/theforeman/foreman-documentation][3] 并点击 “复刻Fork” 按钮。 + +5、将你的复刻添加到你的存储库中： + +``` +$ git remote add github git@github.com:/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、将你的分支 变基rebase 到 `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 \ No newline at end of file diff --git a/sources/tech/20221121.1 ⭐️⭐️ 7 Git tips for technical writers.md b/sources/tech/20221121.1 ⭐️⭐️ 7 Git tips for technical writers.md deleted file mode 100644 index 13c331d6f4..0000000000 --- a/sources/tech/20221121.1 ⭐️⭐️ 7 Git tips for technical writers.md +++ /dev/null @@ -1,131 +0,0 @@ -[#]: 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: " " -[#]: reviewer: " " -[#]: publisher: " " -[#]: url: " " - -7 Git tips for technical writers -====== - -As a technical writer working for [ATIX][1], my tasks include creating and maintaining documentation for [Foreman][2] at [github.com/theforeman/foreman-documentation][3]. Git helps me track versions of content, and to collaborate with the open source community. It's an integral part of storing the results of my work, sharing it, and discussing improvements. My main tools include my browser, OpenSSH to connect to Foreman instances, [Vim][4] to edit source files, and Git to version content. - -This article focuses on recurring challenges when taking the first steps with Git and contributing to Foreman documentation. This is meant for intermediate Git users. - -### Prerequisites - -- You have installed and configured Git on your system. You must at least set your user name and email address. -- You have an account on [github.com][5]. GitHub isn't an open source project itself, but it's the site where many open source Git repositories are stored (including Foreman's documentation.) -- You have forked the [foreman-documentation][3] repository into your own account or organization (for example, _github.com/__My_User_Account__/foreman-documentation_. For more information, see [A step-by-step guide to Git][6] by Kedar Vijay Kulkarni. -- You have added your SSH public key to GitHub. This is necessary to push your changes to GitHub. For more information, see [A short introduction to GitHub][7] by Nicole C. Baratta. - -### Contributing to Foreman documentation - -Foreman is an open source project and thrives on community contributions. The project welcomes everyone and there are only a few requirements to make meaningful contributions. Requirements and conventions are documented in the [README.md][8] and [CONTRIBUTING.md][9] files. - -Here are some of the most frequent tasks when working on Foreman documentation. - -### I want to start working on Foreman documentation - -- Clone the repository from github.com:`$ git clone git@github.com:theforeman/foreman-documentation.git -$ cd foreman-documentation/` -- Rename the remote:`$ git remote rename origin upstream` -- Optional: Ensure that your local master branch is tracking the master branch from the **foreman-documentation** repository from the **theforeman** organization:`$ git status`This automatically starts you on the latest commit of the default branch, which in this case is **master**. -- If you do not have a fork of the repository in your own account or organization already, create one.Go to [github.com/theforeman/foreman-documentation][3] and click **Fork**. -- Add your fork to your repository.`$ git remote add github git@github.com:_My_User_Account_/foreman-documentation.git`Your local repository now has two remotes: `upstream` and `github`. - -### I want to extend the Foreman documentation - -For simple changes such as fixing a spelling mistake, you can create a pull request (PR) directly. - -- Create a branch named, for example, `fix_spelling`. The `git switch` command changes the currently checked out branch, and `-c` creates the branch:`$ git switch -c fix_spelling` -- Make your change. -- Add your change and commit:`$ git add guides/common/modules/abc.adoc -$ git commit -m "Fix spelling of existing"`I cannot emphasise the importance of good Git commit messages enough. A commit message tells contributors what you have done, and because it's preserved along with the rest of the codebase, it serves as a historical footnote when someone's looking back through code to determine what's happened over its lifespan. For more information on great git commit messages, see [The seven rules of a great Git commit message][10] by cbeams. -- Optional but recommended: View and verify the diff to the default branch. The default branch for **foreman-documentation** is called `master`, but other projects may name theirs differently (for example, `main`, `dev`, or `devel`.)`$ git diff master` -- Push your branch to Github. This publishes your change to your copy of the codebase.`$ git push --set-upstream github fix_spelling` -- Click on the link provided by Git in your terminal to create a pull request (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` -- Add an explanation on _why_ the community should accept your change. This isn't necessary for a trivial PR, such as fixing a spelling mistake, but for major changes it's important. - -### I want to rebase my branch to master. - -- Ensure your local master branch tracks the master branch from [github.com/theforeman/foreman-documentation][3], not **foreman-documentation** in your own namespace:`$ git switch master`This should read `Your branch is up to date with 'upstream/master'`, with `upstream` being the name of your remote repository pointing to `github.com/theforeman/foreman-documentation`. You can review your remotes by running `git remote -v`. -- Fetch possible changes from your remote. The `git fetch` command downloads the tracked branch from your remote, and the `--all` option updates all branches simultaneously. This is necessary when working with additional branches. The `--prune` option removes references to branches that no longer exist.`$ git fetch --all --prune` -- Pull possible changes from `upstream/master` into your local `master` branch. The `git pull` command copies commits from the branch you're tracking into your current branch. This is used to "update" your local `master` branch to the latest state of the `master` branch in your remote (Github, in this case.)`$ git pull` -- Rebase your branch to "master".`$ git switch my_branch -$ git rebase -i master` - -### I have accidentally committed to master - -- Create a branch to save your work:`$ git switch -c my_feature` -- Switch back to the `master` branch:`$ git switch master` -- Drop the last commit on `master`:`$ git reset --soft HEAD~1` -- Switch back to `my_feature` branch and continue working:`$ git switch my_feature` - -### I want to reword my commit message - -- If you only have one commit on your branch, use `git amend` to change your last commit:`$ git commit --amend`This assumes that you don't have any other files added to your staging area (that is, you did not run `git add My_File` without also committing it.) -- Push your "change" to Github, using the `--force` option because the Git commit message is part of your existing commit, so you're changing the history on your branch.`$ git push --force` - -### I want to restructure multiple changes on a single branch - -- Use **e** to make actual changes to your commit. This interrupts your rebase! -- Use **f** to combine a commit with its parent. -- Use **d** to completely remove the commit from your branch. -- Move the lines to change the order of your changes.After successfully rebasing, your own commits are on top of the last commit from `master`. - -- Optional but strongly recommended: Fetch changes from Github.`$ git switch master -$ git fetch -$ git pull`This ensures that you directly incorporate any other changes into your branch in the order they've been merged to `master`. -- To restructure your work, rebase your branch and make changes as necessary. Rebasing to `master` means changing the parent commit of your first commit on your branch:`$ git rebase --interactive master`Replace the first word `pick` to modify the commit. - -### I want to copy a commit from another branch - -- Get the commit ID from a stable branch (for example, a branch named `3.3`), using the `-n` option to limit the number of commits.`$ git log -n 5 3.3` -- Replicate changes by cherry-picking commits to your branch. The `-x` option adds the commit ID to your commit message. This is only recommended when cherry-picking commits from a stable branch.`$ git switch My_Branch -$ git cherry-pick -x Commit_ID` - -### More tips - -At ATIX, we run a [GitLab][11] instance to share code, collaborate, and automate tests and builds internally. With the open source community surrounding the Foreman ecosystem, we rely on Github. - -I recommend that you always point the remote named `origin` in any Git repository to your _internal_ version control system. This prevents leaking information to external services when doing a `git push` based on pure muscle memory. - -Additionally, I recommend using a fixed naming scheme for remotes. I always name the remote pointing to my own GitLab instance `origin`, the open source project `upstream`, and my fork on Github `github`. - -For `foreman-documentation`, the repository has a relatively flat history. When working with a more complex structure, I tend to think of Git repositories in a very visual way with nodes (commits) pointing to nodes on lines (branches) that potentially intertwine. Graphical tools such as `gitk` or [Git Cola][12] can help visualize your Git history. Once you have fully grasped how Git works, you can move on to aliases, if you prefer the command line. - -Before a big rebase with a lot of expected merge conflicts, I recommend creating a "backup" branch that you can quickly view diffs against. Note that it's pretty hard to irreversibly delete commits, so play around in your local Git repository before making big changes. - -### Git for tech writers - -Git is a tremendous help for technical writers. Not only can you use Git to version your own content, but you can actively collaborate with others. - --------------------------------------------------------------------------------- - -via: https://opensource.com/article/22/11/git-tips-technical-writers - -作者：[Maximilian Kolb][a] -选题：[lkxed][b] -译者：[Donkey-Hao](https://github.com/Donkey-Hao) -校对：[校对者ID](https://github.com/校对者ID) - -本文由 [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