git/Documentation/git-worktree.txt, branch v2.32.2

worktree: teach `list` verbose mode

2021-01-30T17:57:40Z

"git worktree list" annotates each worktree according to its state such as "prunable" or "locked", however it is not immediately obvious why these worktrees are being annotated. For prunable worktrees a reason is available that is returned by should_prune_worktree() and for locked worktrees a reason might be available provided by the user via `lock` command. Let's teach "git worktree list" a --verbose mode that outputs the reason why the worktrees are being annotated. The reason is a text that can take virtually any size and appending the text on the default columned format will make it difficult to extend the command with other annotations and not fit nicely on the screen. In order to address this shortcoming the annotation is then moved to the next line indented followed by the reason If the reason is not available the annotation stays on the same line as the worktree itself. The output of "git worktree list" with verbose becomes like so: $ git worktree list --verbose ... /path/to/locked-no-reason acb124 [branch-a] locked /path/to/locked-with-reason acc125 [branch-b] locked: worktree with a locked reason /path/to/prunable-reason ace127 [branch-d] prunable: gitdir file points to non-existent location ... Helped-by: Eric Sunshine Signed-off-by: Rafael Silva Reviewed-by: Eric Sunshine Signed-off-by: Junio C Hamano

worktree: teach `list` to annotate prunable worktree

2021-01-30T17:57:35Z

The "git worktree list" command shows the absolute path to the worktree, the commit that is checked out, the name of the branch, and a "locked" annotation if the worktree is locked, however, it does not indicate whether the worktree is prunable. The "prune" command will remove a worktree if it is prunable unless `--dry-run` option is specified. This could lead to a worktree being removed without the user realizing before it is too late, in case the user forgets to pass --dry-run for instance. If the "list" command shows which worktree is prunable, the user could verify before running "git worktree prune" and hopefully prevents the working tree to be removed "accidentally" on the worse case scenario. Let's teach "git worktree list" to show when a worktree is a prunable candidate for both default and porcelain format. In the default format a "prunable" text is appended: $ git worktree list /path/to/main aba123 [main] /path/to/linked 123abc [branch-a] /path/to/prunable ace127 (detached HEAD) prunable In the --porcelain format a prunable label is added followed by its reason: $ git worktree list --porcelain ... worktree /path/to/prunable HEAD abc1234abc1234abc1234abc1234abc1234abc12 detached prunable gitdir file points to non-existent location ... Helped-by: Eric Sunshine Signed-off-by: Rafael Silva Reviewed-by: Eric Sunshine Signed-off-by: Junio C Hamano

worktree: teach `list --porcelain` to annotate locked worktree

2021-01-30T17:57:29Z

Commit c57b3367be (worktree: teach `list` to annotate locked worktree, 2020-10-11) taught "git worktree list" to annotate locked worktrees by appending "locked" text to its output, however, this is not listed in the --porcelain format. Teach "list --porcelain" to do the same and add a "locked" attribute followed by its reason, thus making both default and porcelain format consistent. If the locked reason is not available then only "locked" is shown. The output of the "git worktree list --porcelain" becomes like so: $ git worktree list --porcelain ... worktree /path/to/locked HEAD 123abcdea123abcd123acbd123acbda123abcd12 detached locked worktree /path/to/locked-with-reason HEAD abc123abc123abc123abc123abc123abc123abc1 detached locked reason why it is locked ... In porcelain mode, if the lock reason contains special characters such as newlines, they are escaped with backslashes and the entire reason is enclosed in double quotes. For example: $ git worktree list --porcelain ... locked "worktree's path mounted in\nremovable device" ... Furthermore, let's update the documentation to state that some attributes in the porcelain format might be listed alone or together with its value depending whether the value is available or not. Thus documenting the case of the new "locked" attribute. Helped-by: Phillip Wood Helped-by: Eric Sunshine Signed-off-by: Rafael Silva Reviewed-by: Eric Sunshine Signed-off-by: Junio C Hamano

worktree: teach `repair` to fix multi-directional breakage

2020-12-21T21:44:28Z

`git worktree repair` knows how to repair the two-way links between the repository and a worktree as long as a link in one or the other direction is sound. For instance, if a linked worktree is moved (without using `git worktree move`), repair is possible because the worktree still knows the location of the repository even though the repository no longer knows where the worktree is. Similarly, if the repository is moved, repair is possible since the repository still knows the locations of the worktrees even though the worktrees no longer know where the repository is. However, if both the repository and the worktrees are moved, then links are severed in both directions, and no repair is possible. This is the case even when the new worktree locations are specified as arguments to `git worktree repair`. The reason for this limitation is twofold. First, when `repair` consults the worktree's gitfile (/path/to/worktree/.git) to determine the corresponding /worktrees//gitdir file to fix, is the old path to the repository, thus it is unable to fix the `gitdir` file at its new location since it doesn't know where it is. Second, when `repair` consults /worktrees//gitdir to find the location of the worktree's gitfile (/path/to/worktree/.git), the path recorded in `gitdir` is the old location of the worktree's gitfile, thus it is unable to repair the gitfile since it doesn't know where it is. Fix these shortcomings by teaching `repair` to attempt to infer the new location of the /worktrees//gitdir file when the location recorded in the worktree's gitfile has become stale but the file is otherwise well-formed. The inference is intentionally simple-minded. For each worktree path specified as an argument, `git worktree repair` manually reads the ".git" gitfile at that location and, if it is well-formed, extracts the . It then searches for a corresponding in /worktrees/ and, if found, concludes that there is a reasonable match and updates /worktrees//gitdir to point at the specified worktree path. In order for to be known, `git worktree repair` must be run in the main worktree or bare repository. `git worktree repair` first attempts to repair each incoming /path/to/worktree/.git gitfile to point at the repository, and then attempts to repair outgoing /worktrees//gitdir files to point at the worktrees. This sequence was chosen arbitrarily when originally implemented since the order of fixes is immaterial as long as one side of the two-way link between the repository and a worktree is sound. However, for this new repair technique to work, the order must be reversed. This is because the new inference mechanism, when it is successful, allows the outgoing /worktrees//gitdir file to be repaired, thus fixing one side of the two-way link. Once that side is fixed, the other side can be fixed by the existing repair mechanism, hence the order of repairs is now significant. Two safeguards are employed to avoid hijacking a worktree from a different repository if the user accidentally specifies a foreign worktree as an argument. The first, as described above, is that it requires an match between the repository and the worktree. That itself is not foolproof for preventing hijack, so the second safeguard is that the inference will only kick in if the worktree's /path/to/worktree/.git gitfile does not point at a repository. Signed-off-by: Eric Sunshine Signed-off-by: Junio C Hamano

worktree: teach `list` to annotate locked worktree

2020-10-12T19:24:29Z

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 " 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 Helped-by: Junio C Hamano Helped-by: Eric Sunshine Signed-off-by: Rafael Silva Reviewed-by: Eric Sunshine Signed-off-by: Junio C Hamano

Merge branch 'es/wt-add-detach'

2020-09-19T00:58:04Z

"git worktree add" learns that the "-d" is a synonym to "--detach" option to create a new worktree without being on a branch. * es/wt-add-detach: git-worktree.txt: discuss branch-based vs. throwaway worktrees worktree: teach `add` to recognize -d as shorthand for --detach git-checkout.txt: document -d short option for --detach

git-worktree.txt: discuss branch-based vs. throwaway worktrees

2020-09-07T01:53:56Z

By default, `git worktree add` creates a new worktree associated with a particular branch (which may have been created automatically if not specified explicitly on the command-line). It is also convenient to create throwaway worktrees not associated with any branch, which can be handy when making experimental changes or doing testing. However, the latter use-case may not be obvious to newcomers since the high-level description of worktrees talks only about checking out "more than one branch at a time". Therefore, enhance the description to to discuss both use-cases. A secondary goal of highlighting the distinction between branch-based and throwaway worktrees is to help newcomers understand that the simplest form `git worktree add ` automatically creates a new branch. Stating this early in the description, may help newcomers avoid creating branches without realizing they are doing so, and later wondering why `git branch --list` shows branches the user did not intentionally create. Signed-off-by: Eric Sunshine Signed-off-by: Junio C Hamano

worktree: teach `add` to recognize -d as shorthand for --detach

2020-09-07T01:53:56Z

Like `git switch` and `git checkout`, `git worktree add` can check out a branch or set up a detached HEAD. However, unlike those other commands, `git worktree add` does not understand -d as shorthand for --detach, which may confound users accustomed to using -d for this purpose. Address this shortcoming by teaching `add` to recognize -d for --detach, thus bringing it in line with the other commands. Signed-off-by: Eric Sunshine Signed-off-by: Junio C Hamano

worktree: teach "repair" to fix outgoing links to worktrees

2020-08-31T18:47:45Z

The .git/worktrees//gitdir file points at the location of a linked worktree's .git file. Its content must be of the form /path/to/worktree/.git (from which the location of the worktree itself can be derived by stripping the "/.git" suffix). If the gitdir file is deleted or becomes corrupted or outdated, then Git will be unable to find the linked worktree. An easy way for the gitdir file to become outdated is for the user to move the worktree manually (without using "git worktree move"). Although it is possible to manually update the gitdir file to reflect the new linked worktree location, doing so requires a level of knowledge about worktree internals beyond what a user should be expected to know offhand. Therefore, teach "git worktree repair" how to repair broken or outdated .git/worktrees//gitdir files automatically. (For this to work, the command must either be invoked from within the worktree whose gitdir file requires repair, or from within the main or any linked worktree by providing the path of the broken worktree as an argument to "git worktree repair".) Signed-off-by: Eric Sunshine Signed-off-by: Junio C Hamano

worktree: teach "repair" to fix worktree back-links to main worktree

2020-08-31T18:47:45Z

The .git file in a linked worktree is a "gitfile" which points back to the .git/worktrees/ entry in the main worktree or bare repository. If a worktree's .git file is deleted or becomes corrupted or outdated, then the linked worktree won't know how to find the repository or any of its own administrative files (such as 'index', 'HEAD', etc.). An easy way for the .git file to become outdated is for the user to move the main worktree or bare repository. Although it is possible to manually update each linked worktree's .git file to reflect the new repository location, doing so requires a level of knowledge about worktree internals beyond what a user should be expected to know offhand. Therefore, teach "git worktree repair" how to repair broken or outdated worktree .git files automatically. (For this to work, the command must be invoked from within the main worktree or bare repository, or from within a worktree which has not become disconnected from the repository -- such as one which was created after the repository was moved.) Signed-off-by: Eric Sunshine Signed-off-by: Junio C Hamano