我一直在慢慢地撰写关于 Git 工作原理的文章。尽管我曾认为自己对 Git 非常了解，但像往常一样，当我尝试解释某事的时候，我又学到一些新东西。

现在回想起来，这些事情都不算太令人吃惊，但我以前并没有清楚地思考过它们。

事实是:

• “索引”、“暂存区” 和 -cached 是一回事
• 隐匿文件就是一堆提交
• 并非所有引用都是分支或标签
• 合并提交不是空的

下面我们来详细了解这些内容。

“索引”、“暂存区” 和 -cached 是一回事

当你运行 git add file.txt，然后运行 git status，你会看到类似以下的输出：

$ git add content/post/2023-10-20-some-miscellaneous-git-facts.markdown
$ git status
Changes to be committed:
    (use "git restore --staged <file>..." to unstage)
    new file:   content/post/2023-10-20-some-miscellaneous-git-facts.markdown

人们通常称这个过程为“暂存文件”或“将文件添加到暂存区”。

当你使用 git add 命令来暂存文件时，Git 在后台将文件添加到其对象数据库（在 .git/objects 目录下），并更新一个名为 .git/index 的文件以引用新添加的文件。

Git 中的这个“暂存区”事实上有 3 种不同的名称，但它们都指的是同一个东西（即 .git/index 文件）：

• git diff --cached
• git diff --staged
• .git/index 文件

我觉得我早该早点认识到这一点，但我之前并没有，所以在这里提醒一下。

隐匿文件就是一堆提交

当我运行 git stash 命令来保存更改时，我一直对这些更改究竟去了哪里感到有些困惑。事实上，当你运行 git stash 命令时，Git 会根据你的更改创建一些提交，并用一个名为 stash 的引用来标记它们（在 .git/refs/stash 目录下）。

让我们将此博客文章隐匿起来，然后查看 stash 引用的日志：

$ git log stash --oneline
6cb983fe (refs/stash) WIP on main: c6ee55ed wip
2ff2c273 index on main: c6ee55ed wip
... some more stuff

现在我们可以查看提交 2ff2c273 以查看其包含的内容：

$ git show 2ff2c273  --stat
commit 2ff2c273357c94a0087104f776a8dd28ee467769
Author: Julia Evans <[email protected]>
Date:   Fri Oct 20 14:49:20 2023 -0400

    index on main: c6ee55ed wip

    content/post/2023-10-20-some-miscellaneous-git-facts.markdown | 40 ++++++++++++++++++++++++++++++++++++++++

毫不意外，它包含了这篇博客文章。这很合理！

实际上，git stash 会创建两个独立的提交：一个是索引提交，另一个是你尚未暂存的改动提交。这让我感到很振奋，因为我一直在开发一款工具，用于快照和恢复 Git 仓库的状态（也许永远不会发布），而我提出的设计与 Git 的隐匿实现非常相似，所以我对自己的选择感到满意。

显然 stash 中的旧提交存储在 reflog 中。

并非所有引用都是分支或标签

Git 文档中经常泛泛地提到 “引用”，这使得我有时觉得很困惑。就个人而言，我在 Git 中处理 “引用” 的 99% 时间是指分支或 HEAD，而剩下的 1% 时间是指标签。事实上，我以前完全不知道任何不是分支、标签或 HEAD 的引用示例。

但现在我知道了一个例子—— stash 是一种引用，而它既不是分支也不是标签！所以这太酷啦！

以下是我博客的 Git 仓库中的所有引用（除了 HEAD）：

$ find .git/refs -type f
.git/refs/heads/main
.git/refs/remotes/origin/HEAD
.git/refs/remotes/origin/main
.git/refs/stash

人们在本帖回复中提到的其他一些参考资料：

• refs/notes/*，来自 git notes
• refs/pull/123/head 和 refs/pull/123/head` 用于 GitHub 拉取请求（可通过 git fetch origin refs/pull/123/merge 获取）
• refs/bisect/*，来自 git bisect

合并提交不是空的

这是一个示例 Git 仓库，其中我创建了两个分支 x 和 y，每个分支都有一个文件（x.txt 和 y.txt），然后将它们合并。让我们看看合并提交。

$ git log --oneline
96a8afb (HEAD -> y) Merge branch 'x' into y
0931e45 y
1d8bd2d (x) x

如果我运行 git show 96a8afb，合并提交看起来是“空的”：没有差异！

git show 96a8afb
commit 96a8afbf776c2cebccf8ec0dba7c6c765ea5d987 (HEAD -> y)
Merge: 0931e45 1d8bd2d
Author: Julia Evans <[email protected]>
Date:   Fri Oct 20 14:07:00 2023 -0400

    Merge branch 'x' into y

但是，如果我单独比较合并提交与其两个父提交之间的差异，你会发现当然有差异：

$ git diff 0931e45 96a8afb   --stat
    x.txt | 1 +
    1 file changed, 1 insertion(+)
$ git diff 1d8bd2d 96a8afb   --stat
    y.txt | 1 +
    1 file changed, 1 insertion(+)

现在回想起来，合并提交并不是实际上“空的”（它们是仓库当前状态的快照，就像任何其他提交一样），这一点似乎很明显，只是我以前从未思考为什么它们看起来为空。

显然，这些合并差异为空的原因是合并差异只显示冲突 —— 如果我创建一个带有合并冲突的仓库（一个分支在同一文件中添加了 x，而另一个分支添加了 y），然后查看我解决冲突的合并提交，它看起来会像这样：

$ git show HEAD
commit 3bfe8311afa4da867426c0bf6343420217486594
Merge: 782b3d5 ac7046d
Author: Julia Evans <[email protected]>
Date:   Fri Oct 20 15:29:06 2023 -0400

    Merge branch 'x' into y

diff --cc file.txt
index 975fbec,587be6b..b680253
--- a/file.txt
+++ b/file.txt
@@@ -1,1 -1,1 +1,1 @@@
- y
    -x
++z

这似乎是在告诉我，一个分支添加了 x，另一个分支添加了 y，合并提交通过将 z 替代冲突解决了它。但在前面的示例中，没有冲突，所以 Git 并未显示任何差异。

（感谢 Jordi 告诉我合并差异的工作原理）

先这样吧

些写到这里吧，也许我将在学到更多 Git 知识时撰写另一篇关于 Git 的知识的博客文章。

（题图：MJ/03bfecc3-944e-47a0-a4fd-575293d2ba92）

via: https://jvns.ca/blog/2023/10/20/some-miscellaneous-git-facts/

作者：Julia Evans 选题：lujun9972 译者：KaguyaQiang 校对：wxy

本文由 LCTT 原创编译，Linux中国 荣誉推出

大家好！今天我和一个朋友讨论 Git 的工作原理，我们感到奇怪，Git 是如何存储你的文件的？我们知道它存储在 .git 目录中，但具体到 .git 中的哪个位置，各个版本的历史文件又被存储在哪里呢？

以这个博客为例，其文件存储在一个 Git 仓库中，其中有一个文件名为 content/post/2019-06-28-brag-doc.markdown。这个文件在我的 .git 文件夹中具体的位置在哪里？过去的文件版本又被存储在哪里？那么，就让我们通过编写一些简短的 Python 代码来探寻答案吧。

Git 把文件存储在 .git/objects 之中

你的仓库中，每一个文件的历史版本都被储存在 .git/objects 中。比如，对于这个博客，.git/objects 包含了 2700 多个文件。

$ find .git/objects/ -type f | wc -l
2761

注意：.git/objects 包含的信息，不仅仅是 “仓库中每一个文件的所有先前版本”，但我们暂不详细讨论这一内容。

这里是一个简短的 Python 程序（find-git-object.py），它可以帮助我们定位在 .git/objects 中的特定文件的具体位置。

import hashlib
import sys

def object_path(content):
    header = f"blob {len(content)}\0"
    data = header.encode() + content
    sha1 = hashlib.sha1()
    sha1.update(data)
    digest = sha1.hexdigest()
    return f".git/objects/{digest[:2]}/{digest[2:]}"

with open(sys.argv[1], "rb") as f:
    print(object_path(f.read()))

此程序的主要操作如下：

• 读取文件内容
• 计算一个头部（blob 16673\0），并将其与文件内容合并
• 计算出文件的 sha1 校验和（此处为 e33121a9af82dd99d6d706d037204251d41d54）
• 将这个 sha1 校验和转换为路径（如 .git/objects/e3/3121a9af82dd99d6d706d037204251d41d54）

运行的方法如下：

$ python3 find-git-object.py content/post/2019-06-28-brag-doc.markdown
.git/objects/8a/e33121a9af82dd99d6d706d037204251d41d54

术语解释：“内容寻址存储”

这种存储策略的术语为“ 内容寻址存储 content addressed storage ”，它指的是对象在数据库中的文件名与文件内容的哈希值相同。

内容寻址存储的有趣之处就是，假设我有两份或许多份内容完全相同的文件，在 Git 的数据库中，并不会因此占用额外空间。如果内容的哈希值是 aabbbbbbbbbbbbbbbbbbbbbbbbb，它们都会被存储在 .git/objects/aa/bbbbbbbbbbbbbbbbbbbbb 中。

这些对象是如何进行编码的？

如果我尝试在 .git/objects 目录下查看这个文件，显示的内容似乎有一些奇怪：

$ cat .git/objects/8a/e33121a9af82dd99d6d706d037204251d41d54
x^A<8D><9B>}s<E3>Ƒ<C6><EF>o|<8A>^Q<9D><EC>ju<92><E8><DD><9C><9C>*<89>j<FD>^...

这是怎么回事呢？让我们来运行 file 命令检查一下：

$ file .git/objects/8a/e33121a9af82dd99d6d706d037204251d41d54
.git/objects/8a/e33121a9af82dd99d6d706d037204251d41d54: zlib compressed data

原来，它是压缩的！我们可以编写一个小巧的 Python 程序—— decompress.py，然后用 zlib 模块去解压这些数据：

import zlib
import sys

with open(sys.argv[1], "rb") as f:
    content = f.read()
    print(zlib.decompress(content).decode())

让我们来解压一下看看结果：

$ python3 decompress.py .git/objects/8a/e33121a9af82dd99d6d706d037204251d41d54
blob 16673---
title: "Get your work recognized: write a brag document"
date: 2019-06-28T18:46:02Z
url: /blog/brag-documents/
categories: []
---
... the entire blog post ...

结果显示，这些数据的编码方式非常简单：首先有 blob 16673\0 标识，其后就是文件的全部内容。

这里并没有差异性数据（diff）

这里有一件我第一次知道时让我感到惊讶的事：这里并没有任何差异性数据！那个文件是该篇博客文章的第 9 个版本，但 Git 在 .git/objects 目录中存储的版本是完整文件内容，而并非与前一版本的差异。

尽管 Git 实际上有时候会以差异性数据存储文件（例如，当你运行 git gc 时，为了提升效率，它可能会将多个不同的文件封装成 “打包文件”），但在我个人经验中，我从未需要关注这个细节，所以我们不在此深入讨论。然而，关于这种格式如何工作，Aditya Mukerjee 有篇优秀的文章 《拆解 Git 的打包文件》。

博客文章的旧版本在哪？

你可能会好奇：如果在我修复了一些错别字之前，这篇博文已经存在了 8 个版本，那它们在 .git/objects 目录中的位置是哪里？我们如何找到它们呢？

首先，我们来使用 git log 命令来查找改动过这个文件的每一个提交：

$ git log --oneline  content/post/2019-06-28-brag-doc.markdown
c6d4db2d
423cd76a
7e91d7d0
f105905a
b6d23643
998a46dd
67a26b04
d9999f17
026c0f52
72442b67

然后，我们选择一个之前的提交，比如 026c0f52。提交也被存储在 .git/objects 中，我们可以尝试在那里找到它。但是失败了！因为 ls .git/objects/02/6c* 没有显示任何内容！如果有人告诉你，“我们知道有时 Git 会打包对象来节省空间，我们并不需过多关心它”，但现在，我们需要去面对这个问题了。

那就让我们去解决它吧。

让我们开始解包一些对象

现在我们需要从打包文件中解包出一些对象。我在 Stack Overflow 上查找了一下，看起来我们可以这样进行操作：

$ mv .git/objects/pack/pack-adeb3c14576443e593a3161e7e1b202faba73f54.pack .
$ git unpack-objects < pack-adeb3c14576443e593a3161e7e1b202faba73f54.pack

这种直接对库进行手术式的做法让人有些紧张，但如果我误操作了，我还可以从 Github 上重新克隆这个库，所以我并不太担心。

解包所有的对象文件后，我们得到了更多的对象：大约有 20000 个，而不是原来的大约 2700 个。看起来很酷。

find .git/objects/ -type f | wc -l
20138

我们回头再看看提交

现在我们可以继续看看我们的提交 026c0f52。我们之前说过 .git/objects 中并不都是文件，其中一部分是提交！为了弄清楚我们的旧文章 content/post/2019-06-28-brag-doc.markdown 是在哪里被保存的，我们需要深入查看这个提交。

首先，我们需要在 .git/objects 中查看这个提交。

查看提交的第一步：找到提交

经过解包后，我们现在可以在 .git/objects/02/6c0f5208c5ea10608afc9252c4a56c1ac1d7e4 中找到提交 026c0f52，我们可以用下面的方法去查看它：

$ python3 decompress.py .git/objects/02/6c0f5208c5ea10608afc9252c4a56c1ac1d7e4
commit 211tree 01832a9109ab738dac78ee4e95024c74b9b71c27
parent 72442b67590ae1fcbfe05883a351d822454e3826
author Julia Evans <[email protected]> 1561998673 -0400
committer Julia Evans <[email protected]> 1561998673 -0400

brag doc

我们也可以用 git cat-file -p 026c0f52 命令来获取相同的信息，这个命令能起到相同的作用，但是它在格式化数据时做得更好一些。（-p 选项意味着它能够以更友好的方式进行格式化）

查看提交的第二步：找到树

这个提交包含一个树。树是什么呢？让我们看一下。树的 ID 是 01832a9109ab738dac78ee4e95024c74b9b71c27，我们可以使用先前的 decompress.py 脚本查看这个 Git 对象，尽管我不得不移除 .decode() 才能避免脚本崩溃。

$ python3 decompress.py .git/objects/01/832a9109ab738dac78ee4e95024c74b9b71c27

这个输出的格式有些难以阅读。主要的问题在于，该提交的哈希（\xc3\xf7$8\x9b\x8dO\x19/\x18\xb7}|\xc7\xce\x8e…）是原始字节，而没有进行十六进制的编码，因此我们看到 \xc3\xf7$8\x9b\x8d 而非 c3f76024389b8d。我打算切换至 git cat-file -p 命令，它能以更友好的方式显示数据，我不想自己编写一个解析器。

$ git cat-file -p 01832a9109ab738dac78ee4e95024c74b9b71c27
100644 blob c3f76024389b8d4f192f18b77d7cc7ce8e3a68ad    .gitignore
100644 blob 7ebaecb311a05e1ca9a43f1eb90f1c6647960bc1    README.md
100644 blob 0f21dc9bf1a73afc89634bac586271384e24b2c9    Rakefile
100644 blob 00b9d54abd71119737d33ee5d29d81ebdcea5a37    config.yaml
040000 tree 61ad34108a327a163cdd66fa1a86342dcef4518e    content <-- 这是我们接下来的目标
040000 tree 6d8543e9eeba67748ded7b5f88b781016200db6f    layouts
100644 blob 22a321a88157293c81e4ddcfef4844c6c698c26f    mystery.rb
040000 tree 8157dc84a37fca4cb13e1257f37a7dd35cfe391e    scripts
040000 tree 84fe9c4cb9cef83e78e90a7fbf33a9a799d7be60    static
040000 tree 34fd3aa2625ba784bced4a95db6154806ae1d9ee    themes

这是我在这次提交时库的根目录中所有的文件。看起来我曾经不小心提交了一个名为 mystery.rb 的文件，后来我删除了它。

我们的文件在 content 目录中，接下来让我们看看那个树：61ad34108a327a163cdd66fa1a86342dcef4518e

查看提交的第三步：又一棵树

$ git cat-file -p 61ad34108a327a163cdd66fa1a86342dcef4518e
040000 tree 1168078878f9d500ea4e7462a9cd29cbdf4f9a56    about
100644 blob e06d03f28d58982a5b8282a61c4d3cd5ca793005    newsletter.markdown
040000 tree 1f94b8103ca9b6714614614ed79254feb1d9676c    post <-- 我们接下来的目标！
100644 blob 2d7d22581e64ef9077455d834d18c209a8f05302    profiler-project.markdown
040000 tree 06bd3cee1ed46cf403d9d5a201232af5697527bb    projects
040000 tree 65e9357973f0cc60bedaa511489a9c2eeab73c29    talks
040000 tree 8a9d561d536b955209def58f5255fc7fe9523efd    zines

还未结束……

查看提交的第四步：更多的树……

我们要寻找的文件位于 post/ 目录，因此我们需要进一步探索：

$ git cat-file -p 1f94b8103ca9b6714614614ed79254feb1d9676c
.... 省略了大量行 ...
100644 blob 170da7b0e607c4fd6fb4e921d76307397ab89c1e    2019-02-17-organizing-this-blog-into-categories.markdown
100644 blob 7d4f27e9804e3dc80ab3a3912b4f1c890c4d2432    2019-03-15-new-zine--bite-size-networking-.markdown
100644 blob 0d1b9fbc7896e47da6166e9386347f9ff58856aa    2019-03-26-what-are-monoidal-categories.markdown
100644 blob d6949755c3dadbc6fcbdd20cc0d919809d754e56    2019-06-23-a-few-debugging-resources.markdown
100644 blob 3105bdd067f7db16436d2ea85463755c8a772046    2019-06-28-brag-doc.markdown <-- 我们找到了！！！

在此，2019-06-28-brag-doc.markdown 之所以位于列表最后，是因为在发布时它是最新的博文。

查看提交的第五步：我们终于找到它！

经过努力，我们找到了博文历史版本所在的对象文件！太棒了！它的哈希值是 3105bdd067f7db16436d2ea85463755c8a772046，因此它位于 git/objects/31/05bdd067f7db16436d2ea85463755c8a772046。

我们可以使用 decompress.py 来查看它：

$ python3 decompress.py .git/objects/31/05bdd067f7db16436d2ea85463755c8a772046 | head
blob 15924---
title: "Get your work recognized: write a brag document"
date: 2019-06-28T18:46:02Z
url: /blog/brag-documents/
categories: []
---
... 文件的剩余部分在此 ...

这就是博文的旧版本！如果我执行命令 git checkout 026c0f52 content/post/2019-06-28-brag-doc.markdown 或者 git restore --source 026c0f52 content/post/2019-06-28-brag-doc.markdown，我就会获取到这个版本。

这样遍历树就是 git log 的运行机制

我们刚刚经历的整个过程（找到提交、逐层遍历目录树、搜索所需文件名）看似繁琐，但实际上当我们执行 git log content/post/2019-06-28-brag-doc.markdown 时，背后就是这样在运行。它需要逐个检查你历史记录中的每一个提交，在每个提交中核查 content/post/2019-06-28-brag-doc.markdown 的版本（例如在这个案例中为 3105bdd067f7db16436d2ea85463755c8a772046），并查看它是否自上一提交以来有所改变。

这就是为什么有时 git log FILENAME 会执行的有些缓慢 —— 我的这个仓库中有 3000 个提交，它需要对每个提交做大量的工作，来判断该文件是否在该提交中发生过变化。

我有多少个历史版本的文件？

目前，我在我的博客仓库中跟踪了 1530 个文件：

$ git ls-files | wc -l
1530

但历史文件有多少呢？我们可以列出 .git/objects 中所有的内容，看看有多少对象文件：

$ find .git/objects/ -type f | grep -v pack | awk -F/ '{print $3 $4}' | wc -l
20135

但并不是所有这些都代表过去版本的文件 —— 正如我们之前所见，许多都是提交和目录树。不过，我们可以编写一个小小的 Python 脚本 find-blobs.py，遍历所有对象并检查是否以 blob 开头：

import zlib
import sys

for line in sys.stdin:
    line = line.strip()
    filename = f".git/objects/{line[0:2]}/{line[2:]}"
    with open(filename, "rb") as f:
        contents = zlib.decompress(f.read())
        if contents.startswith(b"blob"):
            print(line)

$ find .git/objects/ -type f | grep -v pack | awk -F/ '{print $3 $4}' | python3 find-blobs.py | wc -l
6713

于是，看起来在我的 Git 仓库中存放的旧文件版本有 6713 - 1530 = 5183 个，Git 会为我保存这些文件，以备我想着要恢复它们时使用。太好了！

就这些啦！

在 这个 gist 中附上了全部的此篇文章所用代码，其实没多少。

我以为我已经对 Git 的工作方式了如指掌，但我以前从未真正涉及过打包文件，所以这次探索很有趣。我也很少思考当我让 git log 跟踪一个文件的历史时，它实际上有多大的工作量，因此也很开心能深入研究这个。

作为一个有趣的后续：我提交这篇博文后，Git 就警告我仓库中的对象太多（我猜 20,000 太多了！），并运行 git gc 将它们全部压缩成打包文件。所以现在我的 .git/objects 目录已经被压缩得十分小了：

$ find .git/objects/ -type f | wc -l
14

（题图：MJ/319a396c-6f3f-4891-b051-261312c8ea9a）

via: https://jvns.ca/blog/2023/09/14/in-a-git-repository--where-do-your-files-live-/

作者：Julia Evans 选题：lujun9972 译者：ChatGPT 校对：wxy

本文由 LCTT 原创编译，Linux中国 荣誉推出

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

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

本文重点介绍在开始使用 Git 和为 Foreman 文档做贡献时经常遇到的挑战。适用于中级 Git 用户。

先决条件

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

对 Foreman 文档做出贡献

Foreman 是一个开源项目，依靠社区的贡献而发展壮大。该项目欢迎所有人的参与，并且只有一些要求才能做出有意义的贡献。这些要求和惯例在 README.md 和 CONTRIBUTING.md 文件中有详细记录。

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

我想开始贡献 Foreman 文档

1、从 github.com 克隆存储库：

$ git clone [email protected]: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 并点击 “ 复刻 Fork ” 按钮。

5、将你的复刻添加到你的存储库中：

$ git remote add github [email protected]:<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 条规则》。

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 的 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 实例，用于内部共享代码、协作以及自动化测试和构建。对于围绕 Foreman 生态系统的开源社区，我们依赖于 GitHub。

我建议你始终将名为 origin 的远程指向你的内部的版本控制系统。这样做可以防止在纯粹凭记忆进行 git push 时向外部服务泄露信息。

此外，我建议使用固定的命名方案来命名远程。我总是将指向自己的 GitLab 实例的远程命名为 origin，将指向开源项目的远程命名为 upstream，将指向我在 Github 上的复刻的远程命名为 github。

对于 foreman-documentation，该存储库具有相对较平的历史记录。当处理更复杂结构时，我倾向于以非常可视化的方式思考 Git 存储库，其中节点（提交）指向线上的节点（分支），这些分支可以交织在一起。图形化工具如 gitk 或 Git Cola 可以帮助可视化你的 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 选题：lkxed 译者：ChatGPT 校对：wxy

本文由 LCTT 原创编译，Linux中国 荣誉推出

在遇到合并冲突时，请不要惊慌。通过一些娴熟的技巧协商，你可以解决任何冲突。

假设你和我正在共同编辑同一个名称为 index.html 的文件。我对文件进行了修改，进行了提交，并将更改推送到 Git 远程仓库。你也对同一个文件进行了修改，进行了提交，并开始将更改推送到同一个 Git 仓库。然而，Git 检测到一个冲突，因为你所做的更改与我所做的更改冲突。

以下是你可以解决冲突的方法：

1、从远程仓库获取并合并最新更改：

$ git pull

2、识别一个或多个有冲突的文件：

$ git status

3、使用文本编辑器打开冲突文件：

$ vim index.html

4、解决冲突。冲突的修改会被标记为 <<<<<<< HEAD 和 >>>>>>>。你需要选择要保留和放弃哪些修改，并手动编辑文件以合并冲突的修改。

以下是一个示例：

<<<<<<< HEAD
<div class="header">
<h1>Sample text 1</h1>
</div>
=======
<div class="header">
<h1>Sample text 2</h1>
</div>
>>>>>>> feature-branch

在这个例子中，我将网站标题更改为 Sample text 1，而你将标题更改为 Sample text 2。两种更改都已添加到文件中。现在你可以决定保留哪一个标题，或者编辑文件以合并更改。在任一情况下，删除指示更改开始和结束的标记，只留下你想要的代码：

<div class="header">
<h1>Sample text 2</h1>
</div>

5、保存所有更改，并关闭编辑器。

6、将文件添加到暂存区：

$ git add index.html

7、提交更改：

$ git commit -m "Updated h1 in index.html"

此命令使用消息 Resolved merge conflict 提交更改。

8、将更改推送到远程仓库：

$ git push

结论

合并冲突是将注意力集中于代码的好理由。你在文件中进行的更改越多，就越容易产生冲突。你应该进行更多的提交，每个提交更改应该更少。你应该避免进行包含多个特性增强或错误修复的单片巨大更改。你的项目经理也会感谢你，因为具有清晰意图的提交更容易追踪。在最初遇到 Git 合并冲突时可能会感到吓人，但是现在你知道如何解决它，你会发现它很容易解决。

（题图：MJ/f432c41a-eb4f-4de0-b2da-f3d8d7a86e26）

via: https://opensource.com/article/23/4/resolve-git-merge-conflicts

作者：Agil Antony 选题：lkxed 译者：ChatGPT 校对：wxy

本文由 LCTT 原创编译，Linux中国 荣誉推出

我请社区的开源从业者分享了他们关于编写有用的 Git 提交信息的建议。

最近，当需要更新时，我一直在密切关注从产品和服务获得的变更日志。以下是一些示例：

• 修复了一些错误。
• 进行了一些可访问性改进。
• 我们已经进行了改进，并修复了错误，以实现更顺畅地运行。

当我想到我还是一名初级开发人员写的一些首次提交信息时，我不得不沮丧地垂下头：

• 用鼠标点了一下，现在一切似乎都正常了。
• 执行了程序员 X 告诉我的操作，现在横幅是蓝色的。

这可真令人沮丧！我向我们的贡献者们提出了以下问题：

• 什么是好的 Git 提交信息？
• 什么是坏的 Git 提交信息？
• 你认为一个项目应该有哪些关于提交信息所写内容的规则？

以下是他们的答案：

易阅读的文笔是关键

与你写任何东西一样，你应该考虑谁会阅读它。然后相应地调整信息的数量和深度。

提高你的自然语言和写作技能对于软件开发的职业生涯顺利发展至关重要。重要的不仅仅是代码。

—— Camilla Conte

具有描述性，不要假设

我在 OpenStack 社区中花了很多时间合作，与我在像“野外”的其他随意的项目中看到的相比，它的代码审查者有一些相当严格的标准。

我花在撰写一条可靠的提交信息的时间，往往要比编写实际的代码实现或修复程序的时间长得多。有时，提交信息可能会比它们解释的代码变化长很多倍。

总结一些贡献者指导：

• 描述为什么要做出改变，而不仅仅是改变了什么
• 第一个提交行是最重要的（就像电子邮件的主题行）
• 不要假设审查者了解你正在修复的原始问题
• 不要假设审查者可以访问外部 Web 服务或网站（总结缺陷报告和其他相关讨论）
• 不要假设代码是不言自明的和自我说明的（尽管没有必要重复你在代码注释中也提出的观点）
• 不要只包含与更改的早期修订相关的信息（我们希望贡献者将修订压扁在一起，并相应地编辑其提交信息）。

《OpenStack 贡献者指南》中有一个关于该主题的 简短章节。

—— Jeremy Stanley

未来的你会感谢自己

我非常同意 Jeremy 的观点。+1000。

Jeremy 说：“描述为什么要做出改变，而不仅仅是改变了什么。”

想象一下，你是旁观者，在遥远的未来试图理解这个提交。

正如老话所说，设身处地为他人着想。

—— Leigh Morresi

使用 bug ID

我建议在提交信息的开头添加 bug ID，这样在以后使用 grep 命令 跟踪提交信息时就会更方便。

例如：

$ git commit -m "BZ#19xxxxx

要写出深思熟虑的提交，请考虑以下事项：

• 我为什么要做这些更改？
• 我的更改产生了什么影响？
• 为什么有更改的必要？
• 更改的依据是什么？

—— Agil Antony

讲述整个故事

我喜欢想象每个提交信息都有一个隐藏的前缀，上面写着 “By applying this（通过应用这个）”。

一个好的提交信息包括将要发生的事情以及原因。仅仅有工单作参考是不够的，因为这分散了信息；Git 是去中心化的。作为一名软件开发人员，我想知道为什么当前要考虑做出更改。正在解决的具体问题是什么？考虑（并放弃）了哪些替代解决方案？在创建变更集的过程中发现了哪些影响当前内容的意外情况？

缩短提交信息没有什么好处。你未来的自己和未来的同事会感激你深入地解释了问题，以及为什么这个变更集是解决方案。认真学习和利用那些内容丰富的“烹饪”博客。然而，在此，仅仅是把生活经验替换成了项目的问题罢了（LCTT 译注：意思是要认真学习和模仿优秀、详细的提交信息）。

—— Lisa Seelye

但不要过于冗长

一个好的 Git 提交信息包含有关所做操作的信息，而不要包含其他信息。例如，如果你需要更新 .gitignore，只需写 “更新了 .gitignore” 即可。人们可以自行深入到提交本身中了解更多细节。它不需要冗长。

糟糕的提交信息类似于“哦，糟糕”或“试试这个”。当然，我也曾经犯过这样的错误，但这对于任何需要一目了然地查看提交信息的人来说都没有任何帮助。

提交信息的规则非常主观。他们可能因领导和团队而异。但至少要提供一些有关提交的上下文信息。特别是如果它是一个大的更改。没有人有时间浏览 1000 多个具有大量更改历史的文件。

—— Miriam Goldman

使用现在时

我喜欢项目经理风格的提交信息，用现在时而不是将来时的术语编写（例如，“添加” 而不是“已添加”）。然而，这通常只有在频繁提交时才有可能。当你面临最后期限时，你能记住的只有“我是如何做的”而已。然而，写得好的提交不仅有助于合作者，而且有助于提交者回忆历史。

—— Chris Okpada

不要依赖链接

我想提醒同事们的一件事是，你不仅仅是向给你的提交作批准的人解释。你还要向未来的开发人员和用户解释，他们在使用 bisect 或 blame 定位问题时发现了这个提交，并试图了解其相关性。

如果提供的唯一的上下文是指向某个外部系统的链接，并且在未来很长一段时间内，它所链接的系统不再使用，或者该用户无法访问，那么你的提交信息将变得无用，可能还不如空白。

我经常去挖掘一些开源项目的 Git 历史，发现有些提交信息无非就是一个 Bug ID，或者是某个公司内部的和专用的缺陷跟踪器的链接。

不要依赖链接！

—— Jeremy Stanley

清晰简洁的变更日志

作为一名发布沟通经理，我会经常阅读整个发布版块。我还会与开发人员会面，讨论任何尚未明确的领域。然后我提前测试了版本。之后，我将通过寻找变更日志和相应的修订或新内容来撰写发布文章。

变更日志是开发人员的个人提醒，但也有相应的提议和工单。你应该适当地将产品名称大写，使用拼写检查器，与标点符号和句子结构保持一致。首席开发人员也应该校对这些。你的客户，即开发人员，正在阅读这些内容。在运行更新之前，他们应该了解哪些信息能更好地为客户服务？

—— Courtney Robertson

具体一点

作为一个经常性的发布经理，我喜欢带有组件名称的提交的信息，以及对更改内容的简要描述。在我们忘记了你聪明的分支名称之后，还可以参考一下这项工作的请求来自何处，这有助于将修复程序联系在一起。

• “修复致命错误”并不是理想的提交。
• “ISS-304: 修复具有合作伙伴角色的用户在登录访问控制功能中的致命错误”更好。
• “ISS-304: 登录访问控制：修复 getPartnerId() 的致命错误”也更好。

我可以查看 Git 提交、分支、合并提交之间的整个关系，并检查更改的各个行和文件。但我在发布过程中没有这样的时间。我希望能够在项目管理工具回溯这项工作的源头，了解哪些组件正在被更改，以及以何种方式进行更改。

—— Ryan Price

让它成为一种习惯

我最喜欢犯的错误是“在我切换分支之前提交”，因为我必须处理其他更紧急的事情。有时候，我需要把我目前的工作提交给一个完全不同的项目。我的经理的策略是让我们像平时一样工作。但当我们变基时，他希望我们在有意义的地方压扁提交，并编写更好的信息。我不能说我们总是这样做，但他的方法确实有道理。

我也有很多“这个坏了，不知道为什么”类型的信息（哈哈），我尝试了一些东西，但想在尝试其他东西之前提交该尝试，以防方法 A 比方法 B 更接近解决问题。我已经写了 10 多年了。

—— RachieVee

你的提交信息建议或提示是什么？让我们在评论中知道。

via: https://opensource.com/article/22/12/git-commit-message

作者：AmyJune Hineline 选题：lkxed 译者：ZhangZhanhaoxiang 校对：wxy

本文由 LCTT 原创编译，Linux中国 荣誉推出

学习如何使用 Git 来压扁、变基和精选。

当我与别人谈到 Git 时，几乎每个人都对 git rebase 命令 有强烈的印象，这个命令让许多人遇到了问题，而不得不更改目录、删除仓库、然后再重新克隆一个仓库。我认为这是因为他们误解了分支是如何工作，遇到了一个非常糟糕的默认界面，还有一些合并冲突把事情搞得一团糟。

怎么找不到 git squash 命令？

如果你曾在本地的仓库提交过很多次，并希望能把这些提交都合并为一个提交，接下来，我们就来介绍能用什么 Git 命令达到这个目的。Git 称这个概念为 “ 压扁提交 squash commits ”。我在编写文档时发现了这个概念：我花了十几个提交才修改好我的 Markdown 文档，但是仓库的维护者不想看到我的所有尝试，以免扰乱了该项目的历史，所以我被告知“需要压扁你的提交”。

压扁提交听起来是一个很有用的方法。但是只有一个问题：我不知道该怎么做。作为 Git 的新手，我做了任何人会做的事情：我去查阅 git-squash 的手册，但我立即遇到了阻碍：

$ man git-squash
> No manual entry for git-squash

我发现没有一个名为 squash 的 Git 命令，而是被要求 运行一个完全独立的命令：git rebase 命令，该命令能将我的所有提交最终合并为一个提交。

我知道我碰到一个常见的情形：已经使用工具一段时间的人使用了行话或引用了一个概念，这个概念对他们来说是非常清楚的，但对新手来说就不能明白了。从概念上讲，这个情况看起来是这样的：

我这样说是为了鼓励你，你绝对不是第一个或最后一个 被 Git 或谈论 Git 的人 弄糊涂的人。你可以要求对方说明白他的意见，并帮助你应该使用的正确命令。仓库的维护者实际上的意思是，“使用 git rebase 命令**，将很多提交压扁成一个提交”。

现在就来学习 git rebase 命令吧

git rebase 命令会将一个提交链从其第一个父级中删除，并将其放置在另一个提交链的末尾，将两个提交链组合成一个长链，而不是两个并行链。我意识到这是一个很复杂的定义。

回想一下 Git 的提交是如何链接在一起的，你可以看到，除了初始的 main（或 master）分支外，任何分支都有一个 父提交 parent commit 作为该链的 “ 基础 base ”。“ 变基 rebase ” 能使另一个链中的最后一个提交成为指定分支的新 “ 基础提交 base commit ”。

在 Git 中整合来自不同分支的修改主要有两种方法： 合并 merge 以及 变基 rebase ，你可能更熟悉 git merge 命令。接下来，就来看看 [git-scm.com] 是如何解释 git merge 和 git rebase 的差异：

在合并示例中，它会把两个分支的最新快照（C3 和 C4）以及二者最近的共同祖先（C2）进行三方合并，合并的结果是生成一个新的快照（C5）。experiment 的分支指针仍然存在，仍然指向 C4。

在变基示例中，它提取在 C4 中引入的补丁和修改，然后在 C3 的基础上应用一次，使 C3 成为 C4 的新父级，并产生了一个名为 C4' 的新提交。

（LCTT 译注：具体的命令如下：

$ git checkout experiment
$ git rebase main
First, rewinding head to replay your work on top of it...
Applying: added staged command

它的原理是首先找到这两个分支 —— 即当前分支 experiment、变基操作的目标基底分支 main —— 的最近共同祖先 C2，然后对比当前分支相对于该祖先的历次提交，提取相应的修改并存为临时文件，然后将当前分支指向目标基底 C3，最后以此将之前另存为临时文件的修改依序应用。）

值得注意的是，分支指针 main 没有移动。要让 Git 将指针移动到链的末尾（由experiment 指向），你还需要执行合并。

（LCTT 译注：具体的命令如下：

$ git checkout main
$ git merge experiment

此时，C4' 指向的快照就和上面使用 merge 命令的例子中 C5 指向的快照一模一样了。）

git rebase 并不能替代 git merge。git rebase 是一种用于制作更清晰的历史记录，以与 git merge 结合使用的工具。

（LCTT 译注：使用 git rebase 命令将提交到某一分支上的所有修改都移至另一分支上，就好像“重新播放”一样。）

交互式变基能给你一个更友好的界面！

从命令行执行 git rebase 命令，最可怕的地方在于它糟糕的默认界面。运行命令 git rebase <target-refr> 要么有效，要么会变得一团糟，因为它没有太多的反馈或方法来确保它做你想做的事情。幸运的是，git rebase 命令和许多其他 Git 命令一样，具有 交互模式 interactive mode ，你可以使用参数 -i 或者 -interactive 来使用交互模式。

在使用交互式模式时，git rebase 会从一个糟糕的黑框界面转换为一个选项菜单，允许你选择对正在变基的提交链所做的事。对于每个提交，你可以选择：

• 选用 pick ：按原样包含
• 重写 reword ：重写提交消息
• 编写 edit ：在变基完成之前对提交中的文件进行进一步更改
• 压扁 squash ：将多个提交压缩成一个提交，保留所有提交消息
• 修理 fixup ：将多个提交压缩成一个提交，但只保留最后一个提交消息
• 丢弃 drop ：丢弃此提交

就我个人而言，我更喜欢 VS Code 的开源 GitLens 扩展 使用下拉选择列表布局选项的方式，但 Git 允许你使用任何编辑器选择这些选项。对于 Emacs 或 Vim 等纯文本工具，你需要键入选择，而不是从菜单中选择，但最终结果仍然是相同的。

何时做变基

知道 何时 做变基与知道 如何 做变基同样重要。事实上，如果你不在乎你的仓库历史提交消息有点混乱的话，那么你可以永远都不使用 git rebase 命令。但是，如果你想要更干净的历史提交消息，并且想要更少扰乱你的图形视图的提交，那么当你使用 git rebase 命令时，有一个重要的经验法则需要时刻记住：

“不要变基你存储库以外的的提交，那些提交可能是别人工作的基础。”

如果你遵循该准则，不会发生什么大问题的。

简而言之，如果你让一个本地分支来完成你的工作，变基是没有问题的。但一旦该分支被 推送 push 了，就不要再变基该分支了。当然，你想要怎么做完全取决于你自己。

希望你会认为上述内容有助于你理解 git rebase 命令的工作原理，并能让你更有信心地使用它。与任何 Git 命令一样，练习是学习和理解怎么做的唯一方法。我鼓励你勇敢地尝试 交互式变基 interactive rebase git rebase -i <branch name>！

接下来学习 Git cherry-pick 命令吧

大多数开发人员将修改提交到某一分支上，但是之后发现他们一直提交到了错误的分支上。理想情况下，他们可以拿走那个提交，然后把它移到正确的分支，这正是 git cherry-pick 命令的作用。

git cherry-pick 命令利用了变基单个提交的方法。这一用法非常常见，以至于有了它自己的命令。

要使用 git cherry-pick，你只需告诉 Git 你要移动到“那个分支”的提交 ID（由 HEAD 指向）：

$ git cherry-pick <target-ref>

如果出现问题，你可以根据 Git 提供的错误消息，来进行恢复：

$ git cherry-pick -i 2bc01cd
Auto-merging README.md
CONFLICT (content): Merge conflict in README.md
error: could not apply 2bc01cd… added EOF lines
hint: After resolving the conflicts, mark them with
hint: "git add/rm ", then run
hint: "git cherry-pick --continue".
hint: You can instead skip this commit with "git cherry-pick --skip".
hint: To abort and get back to the state before "git cherry-pick",
hint: run "git cherry-pick --abort".
$ git cherry-pick --abort

让 Git 更强大

git rebase 命令是 Git 实用程序强大的地方之一。你最好在测试仓库中先练习一下怎么使用，一旦你熟悉了它的概念和工作流程，你就可以给仓库一个清晰历史消息记录了。

via: https://opensource.com/article/22/11/advanced-git-commands

作者：Dwayne McDaniel 选题：lkxed 译者：chai001125 校对：wxy

本文由 LCTT 原创编译，Linux中国 荣誉推出