Re: Orphan branch not well-defined?
- From
Junio C Hamano <gitster@pobox.com>
- Date
- Nov 24, 2023, 02:03 UTC
- Message-ID
- <xmqqwmu79ac4.fsf@gitster.g>
- In-Reply-To
- <CAPx1Gvf_meaEBq9XfS9aPg0yLja-2sAW5SUg0jx6f1jNyfmWHw@mail.gmail.com>
Chris Torek <chris.torek@gmail.com> 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 <<def_merge,merge>> more than two <<def_branch,branches>>. +[[def_orphan]]orphan:: + The act of becoming on an <<def_unborn,unborn>> branch. + After such an operation, the <<def_HEAD,HEAD>> points at a + <<def_branch,branch>> 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 <<def_repository,repository>>. 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 <<def_HEAD,HEAD>> can point at a <<def_branch,branch>> + that does not yet have any <<def_commit,commit>> 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 + <<def_orphan,orphan>> option. + + [[def_unmerged_index]]unmerged index:: An <<def_index,index>> which contains unmerged <<def_index_entry,index entries>>. 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 <new-branch>:: - Create a new 'orphan' branch, named `<new-branch>`, started from + Create a new unborn branch, named `<new-branch>`, started from `<start-point>` 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 <new-branch>:: - Create a new 'orphan' branch, named `<new-branch>`. All + Create a new unborn branch, named `<new-branch>`. 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 `<commit-ish>` 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 `<branch>` (after +associated with a new unborn branch named `<branch>` (after `$(basename <path>)` 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 `<new-branch>`. + the worktree with a new unborn branch named `<new-branch>`. --porcelain:: With `list`, output in an easy-to-parse format for scripts.