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

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

worktree: add -z option for list subcommand

2022-03-31T20:28:55Z

Add a -z option to be used in conjunction with --porcelain that gives NUL-terminated output. As 'worktree list --porcelain' does not quote worktree paths this enables it to handle worktree paths that contain newlines. Signed-off-by: Phillip Wood Signed-off-by: Junio C Hamano

worktree: use 'worktree' over 'working tree'

2022-02-23T20:24:42Z

It is helpful to distinguish between a 'working tree' and a 'worktree'. A worktree contains a working tree plus additional metadata. This metadata includes per-worktree refs and worktree-specific config. This is the last of multiple changes to git-worktree.txt, starting at the LIST OUTPUT FORMAT section. The EXAMPLES section has an instance of "working tree" that must stay as it is, because it is not talking about a worktree, but an example of why a user might want to create a worktree. Helped-by: Taylor Blau Signed-off-by: Derrick Stolee Signed-off-by: Junio C Hamano

worktree: use 'worktree' over 'working tree'

2022-02-23T20:24:42Z