From: Junio C Hamano Date: Fri, 24 Nov 2023 02:03:23 GMT Subject: Re: Orphan branch not well-defined? Message-ID: In-Reply-To: Chris Torek writes: > ** Unborn Branch is the better term ** Yes, To orphan is a verb that denotes the act of becoming on an unborn branch, and a few references to "orphan branch" in our documentation are misuses of the word, I would have to say. I suspect that there are other mentions of "orphan branch" in the code comments, variable names, and even end-user facing messages, some of which may need to be corrected, but the first place to start is in the glossary. How about this? Documentation/glossary-content.txt | 19 +++++++++++++++++++ Documentation/config/advice.txt | 2 +- Documentation/git-checkout.txt | 2 +- Documentation/git-switch.txt | 2 +- Documentation/git-worktree.txt | 4 ++-- 5 files changed, 24 insertions(+), 5 deletions(-) diff --git c/Documentation/glossary-content.txt w/Documentation/glossary-content.txt index 59d8ab8572..bbf7b84ab7 100644 --- c/Documentation/glossary-content.txt +++ w/Documentation/glossary-content.txt @@ -312,6 +312,13 @@ This commit is referred to as a "merge commit", or sometimes just a [[def_octopus]]octopus:: To <> more than two <>. +[[def_orphan]]orphan:: + The act of becoming on an <> branch. + After such an operation, the <> points at a + <> that does not yet exist, and the + commit first created from such a state becomes a root + commit, starting a new history. + [[def_origin]]origin:: The default upstream <>. Most projects have at least one upstream project which they track. By default @@ -695,6 +702,18 @@ The most notable example is `HEAD`. object, etc. +[[def_unborn]]unborn:: + The <> can point at a <> + that does not yet have any <> on it, and + such a branch is called an unborn branch. The most typical + way users encounter an unborn branch is by creating a + repository anew without cloning from elsewhere. The HEAD + would point at the 'main' (or 'master', depending on your + configuration) branch that is yet to be born. Also some + operations can get you on an unborn branch with their + <> option. + + [[def_unmerged_index]]unmerged index:: An <> which contains unmerged <>. diff --git c/Documentation/config/advice.txt w/Documentation/config/advice.txt index 2737381a11..4d7e5d8759 100644 --- c/Documentation/config/advice.txt +++ w/Documentation/config/advice.txt @@ -140,6 +140,6 @@ advice.*:: Advice shown when a fast-forward is not possible. worktreeAddOrphan:: Advice shown when a user tries to create a worktree from an - invalid reference, to instruct how to create a new orphan + invalid reference, to instruct how to create a new unborn branch instead. -- diff --git c/Documentation/git-checkout.txt w/Documentation/git-checkout.txt index 240c54639e..26ad1a5e27 100644 --- c/Documentation/git-checkout.txt +++ w/Documentation/git-checkout.txt @@ -215,7 +215,7 @@ variable. below for details. --orphan :: - Create a new 'orphan' branch, named ``, started from + Create a new unborn branch, named ``, started from `` and switch to it. The first commit made on this new branch will have no parents and it will be the root of a new history totally disconnected from all the other branches and diff --git c/Documentation/git-switch.txt w/Documentation/git-switch.txt index c60fc9c138..3e23a82cf2 100644 --- c/Documentation/git-switch.txt +++ w/Documentation/git-switch.txt @@ -171,7 +171,7 @@ name, the guessing is aborted. You can explicitly give a name with `branch.autoSetupMerge` configuration variable is true. --orphan :: - Create a new 'orphan' branch, named ``. All + Create a new unborn branch, named ``. All tracked files are removed. --ignore-other-worktrees:: diff --git c/Documentation/git-worktree.txt w/Documentation/git-worktree.txt index 93d76f5d66..2a240f53ba 100644 --- c/Documentation/git-worktree.txt +++ w/Documentation/git-worktree.txt @@ -99,7 +99,7 @@ command will refuse to create the worktree (unless `--force` is used). If `` is omitted, neither `--detach`, or `--orphan` is used, and there are no valid local branches (or remote branches if `--guess-remote` is specified) then, as a convenience, the new worktree is -associated with a new orphan branch named `` (after +associated with a new unborn branch named `` (after `$(basename )` if neither `-b` or `-B` is used) as if `--orphan` was passed to the command. In the event the repository has a remote and `--guess-remote` is used, but no remote or local branches exist, then the @@ -234,7 +234,7 @@ This can also be set up as the default behaviour by using the --orphan:: With `add`, make the new worktree and index empty, associating - the worktree with a new orphan/unborn branch named ``. + the worktree with a new unborn branch named ``. --porcelain:: With `list`, output in an easy-to-parse format for scripts.