记一次使用git prune 命令的场景分析

1 异常场景

自动化测试团队在 Jenkins 上配置了用于运行自动化项目的 Job。今天，Job 在执行 git fetch 时报了下面的错误：

自动化团队成员无法解决此问题，于是，我这边帮忙阅读了 Job 的日志，使用 git prune 解决问题；找出了导致此异常场景的原因，并重现场景，让大家了解此场景，避免以后在使用 gitlab 管理代码时再出现此异常场景。

2 日志分析

2.1 git fetch 失败原因

先看日志：

error: cannot lock ref ‘refs/remotes/origin/feature/XXX-3683’: ‘refs/remotes/origin/feature’ exists; cannot create ‘refs/remotes/origin/feature/XXX-3683’
From http://xxx/xxx/auto-testing
! [new branch] feature/XXX-3683 -> origin/feature/XXX-3683 (unable to update local ref)
error: cannot lock ref ‘refs/remotes/origin/feature/XXX-deletion’: ‘refs/remotes/origin/feature’ exists; cannot create ‘refs/remotes/origin/feature/XXX-deletion’
! [new branch] feature/XXX-deletion -> origin/feature/XXX-deletion (unable to update local ref)
error: some local refs could not be updated; try running
‘git remote prune http://xxx/xxx/auto-testing’ to remove any old, conflicting branches

分析以上日志后，我们知道 git fetch 失败的原因是：

(1) remote的仓库新增了 feature/XXX-3683 和 feature/XXX-deletion 两个分支。

(2) 执行 git fetch 时，git 会从远端仓库把 远端分支的信息 同步到本地仓库。远端的 feature/XXX-3683 和 feature/XXX-deletion 的信息会被同步到本地仓库的 refs/remotes/origin/feature/XXX-3683 和 refs/remotes/origin/feature/XXX-deletion 下。

(3) 因为 refs/remotes/origin/feature 已经存在，所以导致 refs/remotes/origin/feature/XXX-3683 和 refs/remotes/origin/feature/XXX-deletion 生成失败。

2.3 解决问题

日志已经告诉了我们解决问题的方法，就是使用以下命令:

git remote prune origin

3 原因分析

3.1 prune 的作用

要找出引发 git fetch 时出现异常的原因，就必须先了解git prune 的作用。

git prune 的作用是：用户在 gitlab 服务端删除了一些 branch，本地仓库中仍然存在这些 远端 branch 的信息，则 git prune 会把这些 远端 branch can残留在本地仓库的信息删除掉。

3.3 .git\refs\remotes\origin 存的是什么

git 的本地仓库中包含一个名为 .git 的隐藏文件夹。当使用 git fetch 或 git pull 拉取代码的时候，除了会拉取当前分支最新代码外，还会同步远端的 branch 信息 到 .git\refs\remotes\origin 中，如下图：

图中的 dev 和 master 两个文件表示 gitlab 服务端存在 dev 和 master 两个 branch。我们可以用笔记本打开 master 文件查看里面的内容：

里面是一串 Hex 字符串，猜想是最新的 commit log id 。在 master 分支下，通过 git log 查看 commit log:

git checkout master
git log

到这里，我们知道了 远端 branch 的信息被保存在 .git\refs\remotes\origin 下，每个 branch 都会生成一个以 branch名命名的文件，文件里面记录着该分支最新的 commit log id。

3.3 导致异常的原因分析

在了解 git prune 的作用后，大概可以推测出引起本次异常的原因了：

(1) 有同事创建了一个名为 feature 的 branch，并 push 到了 gitlab 服务。

(2) Jenkins 的 Job 运行成功，其中会执行 git fetch 把远端 feature 信息同步至 .git\refs\remotes\origin\feature。

(3) 该同事删除了远端的 feature 分支。

(4) 此时，本地仓库的 .git\refs\remotes\origin\feature 依然存在。

(5) 该同事创建了名为 feature/XXX-3683 和 feature/XXX-deletion 两个分支，并 push 到了 gitlab 服务。

(6) 再次运行 Jenkins 的 Job，git fetch 尝试同步 feature/XXX-3683 和 feature/XXX-deletion 的信息至 .git\refs\remotes\origin。

(7) 由于文件 .git\refs\remotes\origin\feature 依然存在，因此 .git\refs\remotes\origin\feature\XXX-3683 及 .git\refs\remotes\origin\feature\XXX-deletion 无法生成，引发了本次异常。

(8) 于是执行 git remote prune origin，.git\refs\remotes\origin\feature 文件会被清除。

(9) 重新运行 Job，git fetch 成功同步 feature/XXX-3683 和 feature/XXX-deletion 的信息至 .git\refs\remotes\origin\feature\XXX-3683 及 .git\refs\remotes\origin\feature\XXX-deletion，Job 运行成功。

4 重现异常场景

在 gitlab 创建 feature branch

执行 git pull 拉取代码

* [new branch] feature -> origin/feature 告诉我们，远程创建了 feature branch，同步该 branch 信息后，在 .git\refs\remotes\origin\ 下生成了 feature 文件：

在 gitlab 删除 feature branch

在 gitlab 新增 feature/XXX-3683 和 feature/XXX-deletion 两个 branch

执行 git pull 拉取代码

此时，相同的异常出现了，始作俑者就是在远端已被删除的 feature branch 在本地的信息文件 .git\refs\remotes\origin\feature。

执行 git remote show origin

可以执行 git remote show origin 查看远端分支情况：

refs/remotes/origin/feature stale (use 'git remote prune' to remove) 告诉我们 feature 在远端仓库已被删除了，可使用 git remote prune origin 删除此分支在本地仓库中的信息，即文件 .git\refs\remotes\origin\feature。

执行 git remote prune origin

* [pruned] origin/feature 告诉我们，.git\refs\remotes\origin\feature 已被清除了。

再执行 git pull

此时，本地仓库生成了文件夹 .git\refs\remotes\origin\feature

feature 文件夹里包含新建的两个分支的信息文件：

5 总结

git prune 可以帮助我们把一些已从远端仓库删除的 branch 残留在本地仓库的信息清除掉。

通过本次异常场景分析后，我建议大家在给 branch 命名时，尽量不要使用 \ 如 feature/XXX-3683，否则在拉取代码时极有可能出现本文描述的异常。