Git worktree：两个worktree指向同一个位置，不能被修剪
Git worktree: two worktrees point in the same location, cannot be prune
当我执行git worktree list时，显示如下。
/path/to/workspace c943d35 [master]
/path/to/workspace ef4df56 (detached HEAD)
这是我的工作目录（不是工作树目录）。我不知道它是怎么发生的，以及如何清理它。我试过 git worktree prune，但它没有任何改变。任何帮助将不胜感激。非常感谢。
Each linked working tree has a private sub-directory in the repository’s $GIT_DIR/worktrees directory.
检查您的 main repo/.git/worktrees 的内容，看看是否有您可以手动删除的子文件夹。
Git 2.20（2018 年第 4 季度）修复了一个错误，在该错误中，如果路径丢失（例如，被手动删除），同一路径可以在多个工作树条目下注册。
另外，为方便起见，扩大--force适用的情况。
参见 commit 684e742 (30 Aug 2018) by Jeff King (peff)。
参见 commit 3a54043, commit f414310, commit 68a6b3a, commit e19831c, commit cb56f55, commit 45059e6, commit 602aaed, commit e5353be, commit 4c5fa9e (28 Aug 2018) by Eric Sunshine (sunshineco)。
（由 Junio C Hamano -- gitster -- in commit 1c515bf 合并，2018 年 9 月 17 日）
worktree: delete .git/worktrees if empty after 'remove'
For cleanliness, "git worktree prune" deletes the .git/worktrees directory if it is empty after pruning is complete.
For consistency, make "git worktree remove <path>" likewise delete .git/worktrees if it is empty after the removal.
同Git2.20，遍历对象可达性时，决定什么
对象是未引用的和可消耗的，也被教导
将其他工作树的每个工作树参考作为起点
防止数据丢失。
参见 commit 14f74d5 (03 Nov 2018), commit c9ef0d9, commit b29759d, commit ab3e1f7, commit 061e420, commit 3a3b9d8 (21 Oct 2018), and commit 8aff1a9, commit 5c79f74 (29 Sep 2018) by Nguyễn Thái Ngọc Duy (pclouds)。
参见 commit a8c754d (21 Oct 2018) by Elijah Newren (newren)。
（由 Junio C Hamano -- gitster -- in commit e146cc9 合并，2018 年 11 月 13 日）
特别是 (commit 3a3b9d8):
refs: new ref types to make per-worktree refs visible to all worktrees
One of the problems with multiple worktree is accessing per-worktree refs of one worktree from another worktree.
This was sort of solved by multiple ref store, where the code can open the ref store of another worktree and has access to the ref space of that worktree.
The problem with this is reporting.
"HEAD" in another ref space is also called "HEAD" like in the current ref space.
In order to differentiate them, all the code must somehow carry the ref store
around and print something like "HEAD from this ref store".
Instead of entering a separate ref space, we make refs from other worktrees available in the current ref space.
So "HEAD" is always HEAD of the current worktree, but then we can have
"worktrees/blah/HEAD" to denote HEAD from a worktree named
"blah".
This syntax coincidentally matches the underlying directory structure which makes implementation a bit easier.
The main worktree has to be treated specially because well... it's
special from the beginning.
So HEAD from the main worktree is acccessible via the name "main-worktree/HEAD" instead of "worktrees/main/HEAD" because "main" could be just another secondary worktree.
This patch also makes it possible to specify refs from one worktree in
another one, e.g.
git log worktrees/foo/HEAD
那（新引用“worktrees/<name>/HEAD”）导致 Git 2.23（2019 年第 2 季度），其中代码现在清理给工作树的名称，以确保这些引用很好-成立。
参见 commit 1de16ae (08 Mar 2019) by Nguyễn Thái Ngọc Duy (pclouds)。
帮助：Jeff King (peff).
（由 Junio C Hamano -- gitster -- in commit 0d107b1 合并，2019 年 6 月 13 日）
worktree add: sanitize worktree names
Worktree names are based on $(basename $GIT_WORK_TREE).
They aren't significant until 3a3b9d8 (refs: new ref types to make per-worktree refs visible to all worktrees - 2018-10-21, Git v2.20.0-rc0), where worktree name could be part of a refname and must follow refname rules.
Update 'worktree add' code to remove special characters to follow
these rules. In the future the user will be able to specify the
worktree name by themselves if they're not happy with this dumb
character substitution.
同样的 Git 2.22.1（2019 年第 3 季度）提到“git worktree add”曾经在连接到同一存储库的另一个工作树损坏时失败，这一点已得到纠正。
参见 commit 105df73 (13 May 2019) by Nguyễn Thái Ngọc Duy (pclouds)。
（由 Junio C Hamano -- gitster -- in commit 933f294 合并，2019 年 7 月 25 日）
worktree add: be tolerant of corrupt worktrees
find_worktree() can die() unexpectedly because it uses real_path()
instead of the gentler version.
When it's used in 'git worktree add' (added in cb56f55 (worktree: disallow adding same path multiple times, 2018-08-28, Git v2.20.0-rc0), or since v2.20.0. Though the real bug in find_worktree() is much older) and there's a bad worktree, this die() could prevent people from adding new worktrees.
The "bad" condition to trigger this is when a parent of the worktree's
location is deleted. Then real_path() will complain.
Use the other version so that bad worktrees won't affect 'worktree add'.
The bad ones will eventually be pruned, we just have to tolerate them for a bit.
在 Git 2.26（2020 年第一季度）之前，在极少数情况下，“git worktree add <path>”可能会认为 <path> 已经是已注册的工作树，即使它不是t，并拒绝添加新的工作树。
这已得到纠正。
参见 commit bb69b3b, commit bb4995f, commit a80c4c2 (24 Feb 2020) by Eric Sunshine (sunshineco)。
（由 Junio C Hamano -- gitster -- in commit 49e5043 合并，2020 年 3 月 5 日）
worktree: don't allow "add" validation to be fooled by suffix matching
Reported-by: Cameron Gunnin
Signed-off-by: Eric Sunshine
"git worktree add <path>" performs various checks before approving <path> as a valid location for the new worktree.
Aside from ensuring that <path> does not already exist, one of the questions it asks is whether <path> is already a registered worktree.
To perform this check, it queries find_worktree() and disallows the "add" operation if find_worktree() finds a match for <path>.
As a convenience, however, find_worktree() casts an overly wide net to allow users to identify worktrees by shorthand in order to keep typing to a minimum.
For instance, it performs suffix matching which, given subtrees "foo/bar" and "foo/baz", can correctly select the latter when asked only for "baz".
"add" validation knows the exact path it is interrogating, so this sort of heuristic-based matching is, at best, questionable for this use-case and, at worst, may may accidentally interpret <path> as matching an existing worktree and incorrectly report it as already registered even when it isn't.
(In fact, validate_worktree_add() already contains a special case to avoid accidentally matching against the main worktree, precisely due to this problem.)
Avoid the problem of potential accidental matching against an existing worktree by instead taking advantage of find_worktree_by_path() which matches paths deterministically, without applying any sort of magic shorthand matching performed by find_worktree().
并且：
worktree: improve find_worktree() documentation
Signed-off-by: Eric Sunshine
Do a better job of explaining that find_worktree()'s main purpose is to locate a worktree based upon input from a user which may be some sort of shorthand for identifying a worktree rather than an actual path.
For instance, one shorthand a user can use to identify a worktree is by unique path suffix (i.e. given worktrees at paths "foo/bar" and "foo/baz", the latter can be identified simply as "baz").
The actual heuristics find_worktree() uses to select a worktree may be expanded in the future (for instance, one day it may allow worktree selection by <id> of the .git/worktrees/<id>/ administrative directory), thus the documentation does not provide a precise description of how matching is performed, instead leaving it open-ended to allow for future enhancement.
While at it, drop mention of the non-NULL requirement of prefix since NULL has long been allowed.
For instance, prefix_filename() has explicitly allowed NULL since 116fb64e43 (prefix_filename: drop length parameter, 2017-03-20, Git v2.13.0-rc0), and find_worktree() itself since e4da43b1f0 (prefix_filename: return newly allocated string, 2017-03-20, Git v2.13.0-rc0).
请注意，同一工作树目录只能注册一次，但“git worktree move”允许违反此不变量，已在 Git 2.28（2020 年第 3 季度）中更正。
参见 commit 810382e, commit d179af6, commit 916133e, commit 4a3ce47, commit dd9609a, commit 1b14d40 (10 Jun 2020), and commit c9b77f2 (08 Jun 2020) by Eric Sunshine (sunshineco)。
（由 Junio C Hamano -- gitster -- in commit 9740ef8 合并，2020 年 6 月 22 日）
使用 Git 2.28（2020 年第 3 季度），同一工作树目录只能注册一次，但“git worktree move”允许违反此不变量，已更正。
参见 commit 810382e, commit d179af6, commit 916133e, commit 4a3ce47, commit dd9609a, commit 1b14d40 (10 Jun 2020), and commit c9b77f2 (08 Jun 2020) by Eric Sunshine (sunshineco)。
（由 Junio C Hamano -- gitster -- in commit 9740ef8 合并，2020 年 6 月 22 日）
worktree: prune duplicate entries referencing same worktree path
Signed-off-by: Eric Sunshine
A fundamental restriction of linked working trees is that there must only ever be a single worktree associated with a particular path, thus "git worktree add" explicitly disallows creation of a new worktree at the same location as an existing registered worktree.
Nevertheless, users can still "shoot themselves in the foot" by mucking with administrative files in .git/worktree/<id>/.
Worse, "git worktree move" is careless and allows a worktree to be moved atop a registered but missing worktree (which can happen, for instance, if the worktree is on removable media).
For instance:
$ git clone foo.git
$ cd foo
$ git worktree add ../bar
$ git worktree add ../baz
$ rm -rf ../bar
$ git worktree move ../baz ../bar
$ git worktree list
.../foo beefd00f [master]
.../bar beefd00f [bar]
.../bar beefd00f [baz]
Help users recover from this form of corruption by teaching "git worktree prune" to detect when multiple worktrees are associated with the same path.
并且：
worktree: prune linked worktree referencing main worktree path
Reported-by: Jonathan Müller
Signed-off-by: Eric Sunshine
"git worktree prune" detects when multiple entries are associated with the same path and prunes the duplicates.
However, it does not detect when a linked worktree points at the path of the main worktree.
Although "git worktree add" disallows creating a new worktree with the same path as the main worktree, such a case can arise outside the control of Git even without the user mucking with .git/worktree/<id>/ administrative files.
For instance:
$ git clone foo.git
$ git -C foo worktree add ../bar
$ rm -rf bar
$ mv foo bar
$ git -C bar worktree list
.../bar deadfeeb [master]
.../bar deadfeeb [bar]
Help the user recover from such corruption by extending "git worktree prune" to also detect when a linked worktree is associated with the path of the main worktree.
请注意 Git 2.30 会列出锁定的工作树：
worktree: teach list to annotate locked worktree
The "git worktree list" shows the absolute path to the working tree,
the commit that is checked out and the name of the branch. It is not
immediately obvious which of the worktrees, if any, are locked.
"git worktree remove" refuses to remove a locked worktree with an error message. If "git worktree list" told which worktrees are locked in its output, the user would not even attempt to remove such a worktree, or would realize that
"git worktree remove -f -f <path>" is required.
Teach "git worktree list" to append "locked" to its output.
The output from the command becomes like so:
$ git worktree list
/path/to/main abc123 [master]
/path/to/worktree 456def (detached HEAD)
/path/to/locked-worktree 123abc (detached HEAD) locked
使用 Git 2.33（2021 年第 3 季度），“git worktree add --lock"(man) 学会了使用自定义消息记录工作树被锁定的原因。
参见 commit 0db4961 (15 Jul 2021), and commit f7c35ea, commit f9365c0 (11 Jul 2021) by Stephen Manz (SRManz)。
（由 Junio C Hamano -- gitster -- in commit 01369fd 合并，2021 年 7 月 28 日）
worktree: teach add to accept --reason <string> with --lock
Signed-off-by: Stephen Manz
Reviewed-by: Eric Sunshine
The default reason stored in the lock file, "added with --lock", is unlikely to be what the user would have given in a separate git worktree lock(man) command.
Allowing --reason to be specified along with --lock when adding a working tree gives the user control over the reason for locking without needing a second command.
git worktree 现在包含在其 man page 中：
git worktree add [-f] [--detach] [--checkout] [--lock [--reason <string>]] [-b <new-branch>] <path> [<commit-ish>]
git worktree 现在包含在其 man page 中：
With lock or with add --lock, an explanation why the working tree is locked.
当我执行git worktree list时，显示如下。
/path/to/workspace c943d35 [master]
/path/to/workspace ef4df56 (detached HEAD)
这是我的工作目录（不是工作树目录）。我不知道它是怎么发生的，以及如何清理它。我试过 git worktree prune，但它没有任何改变。任何帮助将不胜感激。非常感谢。
Each linked working tree has a private sub-directory in the repository’s
$GIT_DIR/worktreesdirectory.
检查您的 main repo/.git/worktrees 的内容，看看是否有您可以手动删除的子文件夹。
Git 2.20（2018 年第 4 季度）修复了一个错误，在该错误中，如果路径丢失（例如，被手动删除），同一路径可以在多个工作树条目下注册。
另外，为方便起见，扩大--force适用的情况。
参见 commit 684e742 (30 Aug 2018) by Jeff King (peff)。
参见 commit 3a54043, commit f414310, commit 68a6b3a, commit e19831c, commit cb56f55, commit 45059e6, commit 602aaed, commit e5353be, commit 4c5fa9e (28 Aug 2018) by Eric Sunshine (sunshineco)。
（由 Junio C Hamano -- gitster -- in commit 1c515bf 合并，2018 年 9 月 17 日）
worktree: delete.git/worktreesif empty after 'remove'
For cleanliness, "
git worktree prune" deletes the.git/worktreesdirectory if it is empty after pruning is complete.For consistency, make "
git worktree remove <path>" likewise delete.git/worktreesif it is empty after the removal.
同Git2.20，遍历对象可达性时，决定什么 对象是未引用的和可消耗的，也被教导 将其他工作树的每个工作树参考作为起点 防止数据丢失。
参见 commit 14f74d5 (03 Nov 2018), commit c9ef0d9, commit b29759d, commit ab3e1f7, commit 061e420, commit 3a3b9d8 (21 Oct 2018), and commit 8aff1a9, commit 5c79f74 (29 Sep 2018) by Nguyễn Thái Ngọc Duy (pclouds)。
参见 commit a8c754d (21 Oct 2018) by Elijah Newren (newren)。
（由 Junio C Hamano -- gitster -- in commit e146cc9 合并，2018 年 11 月 13 日）
特别是 (commit 3a3b9d8):
refs: new ref types to make per-worktree refs visible to all worktrees
One of the problems with multiple worktree is accessing per-worktree refs of one worktree from another worktree.
This was sort of solved by multiple ref store, where the code can open the ref store of another worktree and has access to the ref space of that worktree.The problem with this is reporting.
"HEAD" in another ref space is also called "HEAD" like in the current ref space.
In order to differentiate them, all the code must somehow carry the ref store around and print something like "HEAD from this ref store".Instead of entering a separate ref space, we make refs from other worktrees available in the current ref space.
So "HEAD" is always HEAD of the current worktree, but then we can have "worktrees/blah/HEAD" to denote HEAD from a worktree named "blah".
This syntax coincidentally matches the underlying directory structure which makes implementation a bit easier.The main worktree has to be treated specially because well... it's special from the beginning.
So HEAD from the main worktree is acccessible via the name "main-worktree/HEAD" instead of "worktrees/main/HEAD" because "main" could be just another secondary worktree.This patch also makes it possible to specify refs from one worktree in another one, e.g.
git log worktrees/foo/HEAD
那（新引用“worktrees/<name>/HEAD”）导致 Git 2.23（2019 年第 2 季度），其中代码现在清理给工作树的名称，以确保这些引用很好-成立。
参见 commit 1de16ae (08 Mar 2019) by Nguyễn Thái Ngọc Duy (pclouds)。
帮助：Jeff King (peff).
（由 Junio C Hamano -- gitster -- in commit 0d107b1 合并，2019 年 6 月 13 日）
worktree add: sanitize worktree names
Worktree names are based on
$(basename $GIT_WORK_TREE).
They aren't significant until 3a3b9d8 (refs: new ref types to make per-worktree refs visible to all worktrees - 2018-10-21, Git v2.20.0-rc0), where worktree name could be part of a refname and must follow refname rules.Update '
worktree add' code to remove special characters to follow these rules. In the future the user will be able to specify the worktree name by themselves if they're not happy with this dumb character substitution.
同样的 Git 2.22.1（2019 年第 3 季度）提到“git worktree add”曾经在连接到同一存储库的另一个工作树损坏时失败，这一点已得到纠正。
参见 commit 105df73 (13 May 2019) by Nguyễn Thái Ngọc Duy (pclouds)。
（由 Junio C Hamano -- gitster -- in commit 933f294 合并，2019 年 7 月 25 日）
worktree add: be tolerant of corrupt worktrees
find_worktree()can die() unexpectedly because it usesreal_path()instead of the gentler version.When it's used in 'git worktree add' (added in cb56f55 (
worktree: disallow adding same path multiple times, 2018-08-28, Git v2.20.0-rc0), or since v2.20.0. Though the real bug infind_worktree()is much older) and there's a bad worktree, thisdie()could prevent people from adding new worktrees.The "bad" condition to trigger this is when a parent of the worktree's location is deleted. Then
real_path()will complain.Use the other version so that bad worktrees won't affect '
worktree add'.
The bad ones will eventually be pruned, we just have to tolerate them for a bit.
在 Git 2.26（2020 年第一季度）之前，在极少数情况下，“git worktree add <path>”可能会认为 <path> 已经是已注册的工作树，即使它不是t，并拒绝添加新的工作树。
这已得到纠正。
参见 commit bb69b3b, commit bb4995f, commit a80c4c2 (24 Feb 2020) by Eric Sunshine (sunshineco)。
（由 Junio C Hamano -- gitster -- in commit 49e5043 合并，2020 年 3 月 5 日）
worktree: don't allow "add" validation to be fooled by suffix matchingReported-by: Cameron Gunnin
Signed-off-by: Eric Sunshine
"
git worktreeadd <path>" performs various checks before approving<path>as a valid location for the new worktree.Aside from ensuring that
<path>does not already exist, one of the questions it asks is whether<path>is already a registered worktree.
To perform this check, it queriesfind_worktree()and disallows the "add" operation iffind_worktree()finds a match for<path>.
As a convenience, however,find_worktree()casts an overly wide net to allow users to identify worktrees by shorthand in order to keep typing to a minimum.
For instance, it performs suffix matching which, given subtrees "foo/bar" and "foo/baz", can correctly select the latter when asked only for "baz"."
add" validation knows the exact path it is interrogating, so this sort of heuristic-based matching is, at best, questionable for this use-case and, at worst, may may accidentally interpret<path>as matching an existing worktree and incorrectly report it as already registered even when it isn't.
(In fact,validate_worktree_add()already contains a special case to avoid accidentally matching against the main worktree, precisely due to this problem.)Avoid the problem of potential accidental matching against an existing worktree by instead taking advantage of
find_worktree_by_path()which matches paths deterministically, without applying any sort of magic shorthand matching performed byfind_worktree().
并且：
worktree: improvefind_worktree()documentationSigned-off-by: Eric Sunshine
Do a better job of explaining that
find_worktree()'s main purpose is to locate a worktree based upon input from a user which may be some sort of shorthand for identifying a worktree rather than an actual path.For instance, one shorthand a user can use to identify a worktree is by unique path suffix (i.e. given worktrees at paths "
foo/bar" and "foo/baz", the latter can be identified simply as "baz").
The actual heuristicsfind_worktree()uses to select a worktree may be expanded in the future (for instance, one day it may allow worktree selection by<id>of the.git/worktrees/<id>/administrative directory), thus the documentation does not provide a precise description of how matching is performed, instead leaving it open-ended to allow for future enhancement.While at it, drop mention of the non-NULL requirement of
prefixsinceNULLhas long been allowed.For instance,
prefix_filename()has explicitly allowedNULLsince 116fb64e43 (prefix_filename: drop length parameter, 2017-03-20, Git v2.13.0-rc0), andfind_worktree()itself since e4da43b1f0(prefix_filename: return newly allocated string, 2017-03-20, Git v2.13.0-rc0).
请注意，同一工作树目录只能注册一次，但“git worktree move”允许违反此不变量，已在 Git 2.28（2020 年第 3 季度）中更正。
参见 commit 810382e, commit d179af6, commit 916133e, commit 4a3ce47, commit dd9609a, commit 1b14d40 (10 Jun 2020), and commit c9b77f2 (08 Jun 2020) by Eric Sunshine (sunshineco)。
（由 Junio C Hamano -- gitster -- in commit 9740ef8 合并，2020 年 6 月 22 日）
使用 Git 2.28（2020 年第 3 季度），同一工作树目录只能注册一次，但“git worktree move”允许违反此不变量，已更正。
参见 commit 810382e, commit d179af6, commit 916133e, commit 4a3ce47, commit dd9609a, commit 1b14d40 (10 Jun 2020), and commit c9b77f2 (08 Jun 2020) by Eric Sunshine (sunshineco)。
（由 Junio C Hamano -- gitster -- in commit 9740ef8 合并，2020 年 6 月 22 日）
worktree: prune duplicate entries referencing same worktree pathSigned-off-by: Eric Sunshine
A fundamental restriction of linked working trees is that there must only ever be a single worktree associated with a particular path, thus "
git worktree add" explicitly disallows creation of a new worktree at the same location as an existing registered worktree.Nevertheless, users can still "shoot themselves in the foot" by mucking with administrative files in
.git/worktree/<id>/.Worse, "
git worktree move" is careless and allows a worktree to be moved atop a registered but missing worktree (which can happen, for instance, if the worktree is on removable media).For instance:
$ git clone foo.git $ cd foo $ git worktree add ../bar $ git worktree add ../baz $ rm -rf ../bar $ git worktree move ../baz ../bar $ git worktree list .../foo beefd00f [master] .../bar beefd00f [bar] .../bar beefd00f [baz]Help users recover from this form of corruption by teaching "
git worktree prune" to detect when multiple worktrees are associated with the same path.
并且：
worktree: prune linked worktree referencing main worktree pathReported-by: Jonathan Müller
Signed-off-by: Eric Sunshine
"
git worktree prune" detects when multiple entries are associated with the same path and prunes the duplicates.However, it does not detect when a linked worktree points at the path of the main worktree.
Although "git worktree add" disallows creating a new worktree with the same path as the main worktree, such a case can arise outside the control of Git even without the user mucking with.git/worktree/<id>/administrative files.For instance:
$ git clone foo.git $ git -C foo worktree add ../bar $ rm -rf bar $ mv foo bar $ git -C bar worktree list .../bar deadfeeb [master] .../bar deadfeeb [bar]Help the user recover from such corruption by extending "
git worktree prune" to also detect when a linked worktree is associated with the path of the main worktree.
请注意 Git 2.30 会列出锁定的工作树：
worktree: teach
listto annotate locked worktree
The "
git worktree list" shows the absolute path to the working tree, the commit that is checked out and the name of the branch. It is not immediately obvious which of the worktrees, if any, are locked."git worktree remove" refuses to remove a locked worktree with an error message. If "
git worktree list" told which worktrees are locked in its output, the user would not even attempt to remove such a worktree, or would realize that "git worktree remove -f -f <path>" is required.Teach "
git worktree list" to append "locked" to its output.
The output from the command becomes like so:$ git worktree list /path/to/main abc123 [master] /path/to/worktree 456def (detached HEAD) /path/to/locked-worktree 123abc (detached HEAD) locked
使用 Git 2.33（2021 年第 3 季度），“git worktree add --lock"(man) 学会了使用自定义消息记录工作树被锁定的原因。
参见 commit 0db4961 (15 Jul 2021), and commit f7c35ea, commit f9365c0 (11 Jul 2021) by Stephen Manz (SRManz)。
（由 Junio C Hamano -- gitster -- in commit 01369fd 合并，2021 年 7 月 28 日）
worktree: teachaddto accept--reason <string>with--lockSigned-off-by: Stephen Manz
Reviewed-by: Eric Sunshine
The default reason stored in the lock file, "
added with --lock", is unlikely to be what the user would have given in a separategit worktree lock(man) command.
Allowing--reasonto be specified along with--lockwhen adding a working tree gives the user control over the reason for locking without needing a second command.
git worktree 现在包含在其 man page 中：
git worktree add [-f] [--detach] [--checkout] [--lock [--reason <string>]] [-b <new-branch>] <path> [<commit-ish>]
git worktree 现在包含在其 man page 中：
With
lockor withadd --lock, an explanation why the working tree is locked.