Git worktree 简介

翻译来源：https://www.ruanyifeng.com/blog/2025/05/weekly-issue-348.html

Experiment on your code freely with Git worktree

Get freedom to try things out alongside the security of having a new, linked clone of your repository if your experiment goes wrong.

获得尝试新事物的自由，同时又能在实验失败时拥有一个新的、关联的代码库克隆，从而确保安全。

Git is designed in part to enable experimentation. Once you know that your work is safely being tracked and safe states exist for you to fall back upon if something goes horribly wrong, you're not afraid to try new ideas. Part of the price of innovation, though, is that you're likely to make a mess along the way. Files get renamed, moved, removed, changed, and cut into pieces. New files are introduced. Temporary files that you don't intend to track take up residence in your working directory.

In short, your workspace becomes a house of cards, balancing precariously between "it's almost working!" and "oh no, what have I done?" . So what happens when you need to get your repository back to a known state for an afternoon so that you can get some real work done? The classic commands git branch and git stash come immediately to mind, but neither is designed to deal, one way or another, with untracked files, and changed file paths and other major shifts can make it confusing to just stash your work away for later. The answer is Git worktree.

Git 的设计初衷之一就是支持实验。一旦您知道自己的工作被安全地跟踪，并且存在安全的状态可供您在出现严重错误时回退，您就不会害怕尝试新想法。然而，创新的代价之一是您可能会在过程中制造混乱。文件会被重命名、移动、删除、更改和分割。新的文件会被引入。您无意跟踪的临时文件会出现在您的工作目录中。

简而言之，您的工作区就像一张纸牌屋，在"快成功了！"和"哦不，我做了什么？"之间摇摇欲坠。那么，当您需要在下午将代码库恢复到已知状态以便完成一些实际工作时，会发生什么？经典的命令 git branch 和 git stash 会立刻浮现在脑海中，但它们都没有设计用来处理未跟踪的文件，而且文件路径的更改和其他重大变动可能会让您在稍后恢复工作时感到困惑。答案是 Git 工作树。

What is a Git worktree

A Git worktree is a linked copy of your Git repository, allowing you to have multiple branches checked out at a time. A worktree has a separate path from your main working copy, but it can be in a different state and on a different branch. The advantage of a new worktree in Git is that you can make a change unrelated to your current task, commit the change, and then merge it at a later date, all without disturbing your current work environment.

Git 工作树是您 Git 仓库的一个链接副本，允许您同时检出多个分支。工作树具有与您的主工作副本不同的路径，但它可以处于不同的状态并且位于不同的分支上。Git 中新工作树的优势在于，您可以进行与当前任务无关的更改，提交更改，然后在以后的日期将其合并，而不会干扰当前的工作环境。

The canonical example, straight from the git-worktree man page, is that you're working on an exciting new feature for a project when your project manager tells you there's an urgent fix required. The problem is that your working repository (your "worktree") is in disarray because you're developing a major new feature. You don't want to "sneak" the fix into your current sprint, and you don't feel comfortable stashing changes to create a new branch for the fix. Instead, you decide to create a fresh worktree so that you can make the fix there:

来自 git-worktree 手册页的经典示例是，您正在为项目开发一个令人兴奋的新功能，这时您的项目经理告诉您需要紧急修复一个问题。问题是您的工作仓库（您的"工作树"）处于混乱状态，因为您正在开发一个重要的新功能。您不想将修复"偷偷"纳入当前的冲刺中，也不愿意为了修复问题而暂存更改以创建新分支。相反，您决定创建一个新的工作树，以便在那里进行修复：

$ git branch | tee
* dev
trunk
$ git worktree add -b hotfix ~/code/hotfix trunk
Preparing ../hotfix (identifier hotfix)
HEAD is now at 62a2daf commit

In your code directory, you now have a new directory called hotfix, which is a Git worktree linked to your main project repository, with its HEAD parked at the branch called trunk. You can now treat this worktree as if it were your main workspace. You can change directory into it, make the urgent fix, commit it, and eventually remove the worktree:

在您的代码目录中，现在有一个名为 hotfix 的新目录，这是一个与您的主项目仓库关联的 Git 工作树，其 HEAD 停留在名为 trunk 的分支上。现在您可以将此工作树视为您的主工作区。您可以切换到该目录，进行紧急修复，提交更改，最后删除该工作树：

$ cd ~/code/hotfix
$ sed -i 's/teh/the/' hello.txt
$ git commit --all --message 'urgent hot fix'

Once you've finished your urgent work, you can return to your previous task. You're in control of when your hotfix gets integrated into the main project. For instance, you can push the change directly from its worktree to the project's remote repo:

一旦你完成了紧急的工作，你就可以回到之前的任务上。您可以控制何时将热修复程序集成到主项目中。例如，你可以直接将更改从工作树推送到项目的远程repo：

$ git push origin HEAD
$ cd ~/code/myproject

Or you can archive the worktree as a TAR or ZIP file:

或者您可以将工作树存档为TAR或ZIP文件：

$ cd ~/code/myproject
$ git archive --format tar --output hotfix.tar master

Or you can fetch the changes locally from the separate worktree:

或者你也可以从单独的工作树中获取本地更改：

$ git worktree list
/home/seth/code/myproject  15fca84 [dev]
/home/seth/code/hotfix     09e585d [master]

From there, you can merge your changes using whatever strategy works best for you and your team.

从那里，您可以使用任何最适合您和您的团队的策略合并您的更改。

Listing active worktrees

You can get a list of the worktrees and see what branch each has checked out using the git worktree list command:

你可以使用git worktree list命令获取工作树的列表，并查看每个分支都签出了哪些分支：

$ git worktree list
/home/seth/code/myproject  15fca84 [dev]
/home/seth/code/hotfix     09e585d [master]

You can use this from within either worktree. Worktrees are always linked (unless you manually move them, breaking Git's ability to locate a worktree, and therefore severing the link).

您可以在任何一个工作树中使用它。工作树总是链接的（除非你手动移动它们，破坏了Git定位工作树的能力，从而切断了链接）。

Moving a worktree

Git tracks the locations and states of a worktree in your project's .git directory:

Git会跟踪项目.git目录下工作树的位置和状态：

$ cat ~/code/myproject/.git/worktrees/hotfix/gitdir 
/home/seth/code/hotfix/.git

If you need to relocate a worktree, you must do that using git worktree move; otherwise, when Git tries to update the worktree's status, it fails:

如果你需要重新定位一个工作树，你必须使用git worktree move；否则，当Git尝试更新工作树的状态时，它会失败：

$ mkdir ~/Temp
$ git worktree move hotfix ~/Temp
$ git worktree list
/home/seth/code/myproject  15fca84 [dev]
/home/seth/Temp/hotfix     09e585d [master]

Removing a worktree

When you're finished with your work, you can remove it with the remove subcommand:

当你完成了你的工作，你可以用remove子命令删除它：

$ git worktree remove hotfix
$ git worktree list
/home/seth/code/myproject  15fca84 [dev]

To ensure your .git directory is clean, use the prune subcommand after removing a worktree:

为了确保你的。git目录是干净的，在删除工作树后使用prune子命令：

$ git worktree prune

When to use worktrees

As with many options, whether it's tabs or bookmarks or automatic backups, it's up to you to keep track of the data you generate, or it could get overwhelming. Don't use worktrees so often that you end up with 20 copies of your repo, each in a slightly different state. I find it best to create a worktree, do the task that requires it, commit the work, and then remove the tree. Keep it simple and focused.

The important thing is that worktrees provide improved flexibility for how you manage a Git repository. Use them when you need them, and never again scramble to preserve your working state just to check something on another branch.

与许多选项一样，无论是选项卡、书签还是自动备份，都由您来跟踪生成的数据，否则可能会让您不知所措。不要太频繁地使用工作树，否则你最终会得到20个repo副本，每个副本的状态都略有不同。我发现最好是创建一个工作树，完成需要它的任务，提交工作，然后删除树。保持简单和重点。

重要的是，工作树为管理Git存储库提供了更好的灵活性。当你需要它们的时候就使用它们，再也不要为了检查另一个分支上的东西而匆忙地保存你的工作状态。

来自: Experiment on your code freely with Git worktree | Opensource.com