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

worktree: add relative cli/config options to `repair` command

2024-12-02T00:36:17Z

This teaches the `worktree repair` command to respect the `--[no-]relative-paths` CLI option and `worktree.useRelativePaths` config setting. If an existing worktree with an absolute path is repaired with `--relative-paths`, the links will be replaced with relative paths, even if the original path was correct. This allows a user to covert existing worktrees between absolute/relative as desired. To simplify things, both linking files are written when one of the files needs to be repaired. In some cases, this fixes the other file before it is checked, in other cases this results in a correct file being written with the same contents. Signed-off-by: Caleb White Signed-off-by: Junio C Hamano

worktree: add relative cli/config options to `add` command

2024-12-02T00:36:17Z

This introduces the `--[no-]relative-paths` CLI option and `worktree.useRelativePaths` configuration setting to the `worktree add` command. When enabled these options allow worktrees to be linked using relative paths, enhancing portability across environments where absolute paths may differ (e.g., containerized setups, shared network drives). Git still creates absolute paths by default, but these options allow users to opt-in to relative paths if desired. The t2408 test file is removed and more comprehensive tests are written for the various worktree operations in their own files. Signed-off-by: Caleb White Signed-off-by: Junio C Hamano

worktree: repair copied repository and linked worktrees

2024-09-23T17:08:32Z

For each linked worktree, Git maintains two pointers: (1) /worktrees//gitdir which points at the linked worktree, and (2) /.git which points back at /worktrees/. Both pointers are absolute pathnames. Aside from manually manipulating those raw files, it is possible to easily "break" one or both pointers by ignoring the "git worktree move" command and instead manually moving a linked worktree, moving the repository, or moving both. The "git worktree repair" command was invented to handle this case by restoring these pointers to sane values. For the "repair" command, the "git worktree" manual page states: Repair worktree administrative files, if possible, if they have become corrupted or outdated due to external factors. The "if possible" clause was chosen deliberately to convey that the existing implementation may not be able to fix every possible breakage, and to imply that improvements may be made to handle other types of breakage. A recent problem report[*] illustrates a case in which "git worktree repair" not only fails to fix breakage, but actually causes breakage. Specifically, if a repository / main-worktree and linked worktrees are *copied* as a unit (rather than *moved*), then "git worktree repair" run in the copy leaves the copy untouched but botches the pointers in the original repository and the original worktrees. For instance, given this directory structure: orig/ main/ (main-worktree) linked/ (linked worktree) if "orig" is copied (not moved) to "dup", then immediately after the manual copy operation: * orig/main/.git/worktrees/linked/gitdir points at orig/linked/.git * orig/linked/.git points at orig/main/.git/worktrees/linked * dup/main/.git/worktrees/linked/gitdir points at orig/linked/.git * dup/linked/.git points at orig/main/.git/worktrees/linked So, dup/main thinks its linked worktree is orig/linked, and worktree dup/linked thinks its repository / main-worktree is orig/main. "git worktree repair" is reasonably simple-minded; it wants to trust valid-looking pointers, hence doesn't try to second-guess them. In this case, when validating dup/linked/.git, it finds a legitimate repository pointer, orig/main/.git/worktrees/linked, thus trusts that is correct, but does notice that gitdir in that directory doesn't point at dup/linked/.git, so it (incorrectly) _fixes_ orig/main/.git/worktrees/linked/gitdir to point at dup/linked/.git. Similarly, when validating dup/main/.git/worktrees/linked/gitdir, it finds a legitimate worktree pointer, orig/linked/.git, but notices that its .git file doesn't point back at dup/main, thus (incorrectly) _fixes_ orig/linked/.git to point at dup/main/.git/worktrees/linked. Hence, it has modified and broken the linkage between orig/main and orig/linked rather than fixing dup/main and dup/linked as expected. Fix this problem by also checking if a plausible .git/worktrees/ exists in the *current* repository -- not just in the repository pointed at by the worktree's .git file -- and comparing whether they are the same. If not, then it is likely because the repository / main-worktree and linked worktrees were copied, so prefer the discovered plausible pointer rather than the one from the existing .git file. [*]: https://lore.kernel.org/git/E1sr5iF-0007zV-2k@binarylane-bailey.stuart.id.au/ Reported-by: Russell Stuart Signed-off-by: Eric Sunshine Signed-off-by: Junio C Hamano

orphan/unborn: add to the glossary and use them consistently

2023-11-24T03:11:23Z

To orphan is a verb that denotes the act of getting on an unborn branch, and a few references to "orphan branch" in our documentation are misuses of the word. They caused end-user confusion, which was made even worse because we did not have the term defined in the glossary document. Add entries for "unborn" branch and "orphan" operation to the glossary, and adjust existing documentation accordingly. Signed-off-by: Junio C Hamano

doc/git-worktree: mention "refs/rewritten" as per-worktree refs

2023-10-10T16:23:16Z

Some references are special in the context of worktrees as they are considered to be per-worktree instead of shared across all of the worktrees. Most importantly, this includes "refs/worktree/" that have explicitly been designed such that users can create per-woorktree refs. But there are also special references that have an associated meaning like "refs/bisect/", which is used to track state of git-bisect(1). These special per-worktree references are documented in git-worktree(1), but one instance is missing. In a9be29c9817 (sequencer: make refs generated by the `label` command worktree-local, 2018-04-25), we have converted "refs/rewritten/" to be a per-worktree reference as well. These references are used by our sequencer infrastructure to generate labels for rebased commits. So in order to allow for multiple concurrent rebases to happen in different worktrees, these references need to be tracked per worktree. We forgot to update our documentation to mention these new per-worktree references, which is fixed by this patch. Signed-off-by: Patrick Steinhardt Signed-off-by: Junio C Hamano

worktree add: extend DWIM to infer --orphan

2023-05-17T22:55:25Z

Extend DWIM to try to infer `--orphan` when in an empty repository. i.e. a repository with an invalid/unborn HEAD, no local branches, and if `--guess-remote` is used then no remote branches. This behavior is equivalent to `git switch -c` or `git checkout -b` in an empty repository. Also warn the user (overriden with `-f`/`--force`) when they likely intend to checkout a remote branch to the worktree but have not yet fetched from the remote. i.e. when using `--guess-remote` and there is a remote but no local or remote refs. Current Behavior: % git --no-pager branch --list --remotes % git remote origin % git workree add ../main hint: If you meant to create a worktree containing a new orphan branch [...] hint: Disable this message with "git config advice.worktreeAddOrphan false" fatal: invalid reference: HEAD % git workree add --guess-remote ../main hint: If you meant to create a worktree containing a new orphan branch [...] hint: Disable this message with "git config advice.worktreeAddOrphan false" fatal: invalid reference: HEAD % git fetch --quiet % git --no-pager branch --list --remotes origin/HEAD -> origin/main origin/main % git workree add --guess-remote ../main Preparing worktree (new branch 'main') branch 'main' set up to track 'origin/main'. HEAD is now at dadc8e6dac commit message % New Behavior: % git --no-pager branch --list --remotes % git remote origin % git workree add ../main No possible source branch, inferring '--orphan' Preparing worktree (new branch 'main') % git worktree remove ../main % git workree add --guess-remote ../main fatal: No local or remote refs exist despite at least one remote present, stopping; use 'add -f' to overide or fetch a remote first % git workree add --guess-remote -f ../main No possible source branch, inferring '--orphan' Preparing worktree (new branch 'main') % git worktree remove ../main % git fetch --quiet % git --no-pager branch --list --remotes origin/HEAD -> origin/main origin/main % git workree add --guess-remote ../main Preparing worktree (new branch 'main') branch 'main' set up to track 'origin/main'. HEAD is now at dadc8e6dac commit message % Signed-off-by: Jacob Abel Signed-off-by: Junio C Hamano

worktree add: add --orphan flag

2023-05-17T22:55:24Z

Add support for creating an orphan branch when adding a new worktree. The functionality of this flag is equivalent to git switch's --orphan option. Current Behavior: % git -C foo.git --no-pager branch -l + main % git -C foo.git worktree add main/ Preparing worktree (new branch 'main') HEAD is now at 6c93a75 a commit % % git init bar.git Initialized empty Git repository in /path/to/bar.git/ % git -C bar.git --no-pager branch -l % git -C bar.git worktree add main/ Preparing worktree (new branch 'main') fatal: not a valid object name: 'HEAD' % New Behavior: % git -C foo.git --no-pager branch -l + main % git -C foo.git worktree add main/ Preparing worktree (new branch 'main') HEAD is now at 6c93a75 a commit % % git init --bare bar.git Initialized empty Git repository in /path/to/bar.git/ % git -C bar.git --no-pager branch -l % git -C bar.git worktree add main/ Preparing worktree (new branch 'main') fatal: invalid reference: HEAD % git -C bar.git worktree add --orphan -b main/ Preparing worktree (new branch 'main') % git -C bar.git worktree add --orphan -b newbranch worktreedir/ Preparing worktree (new branch 'newbranch') % Signed-off-by: Ævar Arnfjörð Bjarmason Signed-off-by: Jacob Abel Signed-off-by: Junio C Hamano

worktree add: include -B in usage docs

2023-05-17T22:55:24Z

Document `-B` next to where `-b` is already documented to bring the usage docs in line with other commands such as git checkout. Signed-off-by: Jacob Abel Signed-off-by: Junio C Hamano

doc txt & -h consistency: word-wrap

2022-10-13T16:32:55Z

Change the documentation and -h output for those built-in commands where both the -h output and *.txt were lacking in word-wrapping. There are many more built-ins that could use this treatment, this change is narrowed to those where this whitespace change is needed to make the -h and *.txt consistent in the end. In the case of "Documentation/git-hash-object.txt" and "builtin/hash-object.c" this is not a "doc txt & -h consistency" change, as we're changing both versions, doing so here makes a subsequent change smaller. Signed-off-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano

Merge branch 'pw/worktree-list-with-z'

2022-04-04T17:56:25Z

"git worktree list --porcelain" did not c-quote pathnames and lock reasons with unsafe bytes correctly, which is worked around by introducing NUL terminated output format with "-z". * pw/worktree-list-with-z: worktree: add -z option for list subcommand