Re: Orphan branch not well-defined?

[Junio C Hamano <gitster@pobox.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.