orphan/unborn: add to the glossary and use them consistently
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 <gitster@pobox.com>
Junio C Hamano committed
Nov 24, 2023 at 12:09 UTC
49dc156376e33ae62f84141f4425b2bf2978ad68
5 files changed
+23
-5
Documentation/config/advice.txt
+1
-1
@@ -140,6 +140,6 @@ advice.*::
140
Advice shown when a fast-forward is not possible.
141
worktreeAddOrphan::
142
Advice shown when a user tries to create a worktree from an
143
- invalid reference, to instruct how to create a new orphan
143
+ invalid reference, to instruct how to create a new unborn
144
branch instead.
145
--
Documentation/git-checkout.txt
+1
-1
@@ -215,7 +215,7 @@ variable.
215
below for details.
216
217
--orphan <new-branch>::
218
- Create a new 'orphan' branch, named `<new-branch>`, started from
218
+ Create a new unborn branch, named `<new-branch>`, started from
219
`<start-point>` and switch to it. The first commit made on this
220
new branch will have no parents and it will be the root of a new
221
history totally disconnected from all the other branches and
Documentation/git-switch.txt
+1
-1
@@ -171,7 +171,7 @@ name, the guessing is aborted. You can explicitly give a name with
171
`branch.autoSetupMerge` configuration variable is true.
172
173
--orphan <new-branch>::
174
- Create a new 'orphan' branch, named `<new-branch>`. All
174
+ Create a new unborn branch, named `<new-branch>`. All
175
tracked files are removed.
176
177
--ignore-other-worktrees::
Documentation/git-worktree.txt
+2
-2
@@ -99,7 +99,7 @@ command will refuse to create the worktree (unless `--force` is used).
99
If `<commit-ish>` is omitted, neither `--detach`, or `--orphan` is
100
used, and there are no valid local branches (or remote branches if
101
`--guess-remote` is specified) then, as a convenience, the new worktree is
102
-associated with a new orphan branch named `<branch>` (after
102
+associated with a new unborn branch named `<branch>` (after
103
`$(basename <path>)` if neither `-b` or `-B` is used) as if `--orphan` was
104
passed to the command. In the event the repository has a remote and
105
`--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
234
235
--orphan::
236
With `add`, make the new worktree and index empty, associating
237
- the worktree with a new orphan/unborn branch named `<new-branch>`.
237
+ the worktree with a new unborn branch named `<new-branch>`.
238
239
--porcelain::
240
With `list`, output in an easy-to-parse format for scripts.
Documentation/glossary-content.txt
+18
@@ -312,6 +312,12 @@ This commit is referred to as a "merge commit", or sometimes just a
312
[[def_octopus]]octopus::
313
To <<def_merge,merge>> more than two <<def_branch,branches>>.
314
315
+[[def_orphan]]orphan::
316
+ The act of getting on a <<def_branch,branch>> that does not
317
+ exist yet (i.e., an <<def_unborn,unborn>> branch). After
318
+ such an operation, the commit first created becomes a commit
319
+ without a parent, starting a new history.
320
+
321
[[def_origin]]origin::
322
The default upstream <<def_repository,repository>>. Most projects have
323
at least one upstream project which they track. By default
@@ -695,6 +701,18 @@ The most notable example is `HEAD`.
701
object,
702
etc.
703
704
+[[def_unborn]]unborn::
705
+ The <<def_HEAD,HEAD>> can point at a <<def_branch,branch>>
706
+ that does not yet exist and that does not have any commit on
707
+ it yet, and such a branch is called an unborn branch. The
708
+ most typical way users encounter an unborn branch is by
709
+ creating a repository anew without cloning from elsewhere.
710
+ The HEAD would point at the 'main' (or 'master', depending
711
+ on your configuration) branch that is yet to be born. Also
712
+ some operations can get you on an unborn branch with their
713
+ <<def_orphan,orphan>> option.
714
+
715
+
716
[[def_unmerged_index]]unmerged index::
717
An <<def_index,index>> which contains unmerged
718
<<def_index_entry,index entries>>.