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>

diff --git a/Documentation/config/advice.txt b/Documentation/config/advice.txt
index 2737381a11a1b40dfb2ec3f6f6b182f83a91c9fd..4d7e5d875998fe1c3aa20c0bb5efdcf9fb6fad91 100644 (file)
--- a/Documentation/config/advice.txt
+++ b/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 a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 240c54639e8e85b5a3ecf1fb8fec0266614ec9b5..26ad1a5e27cc5af3334b49908ef1814ed315e180 100644 (file)
--- a/Documentation/git-checkout.txt
+++ b/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 a/Documentation/git-switch.txt b/Documentation/git-switch.txt
index c60fc9c138b5981ce5727efa4482350e699dbac5..3e23a82cf2627acf551274ab014b6410df35b80b 100644 (file)
--- a/Documentation/git-switch.txt
+++ b/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 a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt
index 93d76f5d665a57a8bdca565add921cbd8b76bc37..2a240f53ba7f987b367a7fef689fe916543dedfd 100644 (file)
--- a/Documentation/git-worktree.txt
+++ b/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.

diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt
index 59d8ab85721b93daaaa597eab45ab42cc0a9e6ff..e71dd03f0ce3a6d9afe769a3c1f8960840e6b884 100644 (file)
--- a/Documentation/glossary-content.txt
+++ b/Documentation/glossary-content.txt
@@ -312,6 +312,12 @@ 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 getting on a <<def_branch,branch>> that does not
+       exist yet (i.e., an <<def_unborn,unborn>> branch).  After
+       such an operation, the commit first created becomes a commit
+       without a parent, 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 +701,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 exist and that does not have any commit on
+       it yet, 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>>.