Merge branch 'jc/orphan-unborn'

Doc updates to clarify what an "unborn branch" means.

* jc/orphan-unborn:
  orphan/unborn: fix use of 'orphan' in end-user facing messages
  orphan/unborn: add to the glossary and use them consistently

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 55a50b5b23a18fe2b991555253d781676806e987..8bdfa54ab09b4c4e8e4cb61767527e2ec06900b2 100644 (file)
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -217,7 +217,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 6137421ede01315a8c14465b7a88fb189f1a4d7f..f38e4c8afa1bcbcfba7bd8b3e1da0bbad9703f77 100644 (file)
--- a/Documentation/git-switch.txt
+++ b/Documentation/git-switch.txt
@@ -176,7 +176,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 fbbb3f2de3dc80a280041b3fd951149dc86b83e6..f7d98c11e3dd0821094ae82cb488606a0de14732 100644 (file)
--- a/Documentation/glossary-content.txt
+++ b/Documentation/glossary-content.txt
@@ -314,6 +314,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
@@ -697,6 +703,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>>.

diff --git a/builtin/checkout.c b/builtin/checkout.c
index 59cca80dd443b05ea6b35dc38f22b0522c97ce20..a1e09690cdfcdfc0fdad7b5f3bf5fb12315f2e2b 100644 (file)
--- a/builtin/checkout.c
+++ b/builtin/checkout.c
@@ -1650,7 +1650,7 @@ static struct option *add_common_switch_branch_options(
                        parse_opt_tracking_mode),
                OPT__FORCE(&opts->force, N_("force checkout (throw away local modifications)"),
                           PARSE_OPT_NOCOMPLETE),
-               OPT_STRING(0, "orphan", &opts->new_orphan_branch, N_("new-branch"), N_("new unparented branch")),
+               OPT_STRING(0, "orphan", &opts->new_orphan_branch, N_("new-branch"), N_("new unborn branch")),
                OPT_BOOL_F(0, "overwrite-ignore", &opts->overwrite_ignore,
                           N_("update ignored files (default)"),
                           PARSE_OPT_NOCOMPLETE),

diff --git a/builtin/worktree.c b/builtin/worktree.c
index 4ac16215416a004e9e0a5db321fa6d56c7f6c9ab..cac83a94197dd60054d5266de8cc1b5186ea2b35 100644 (file)
--- a/builtin/worktree.c
+++ b/builtin/worktree.c
@@ -49,14 +49,14 @@
        _("No possible source branch, inferring '--orphan'")
 
 #define WORKTREE_ADD_ORPHAN_WITH_DASH_B_HINT_TEXT \
-       _("If you meant to create a worktree containing a new orphan branch\n" \
+       _("If you meant to create a worktree containing a new unborn branch\n" \
        "(branch with no commits) for this repository, you can do so\n" \
        "using the --orphan flag:\n" \
        "\n" \
        "    git worktree add --orphan -b %s %s\n")
 
 #define WORKTREE_ADD_ORPHAN_NO_DASH_B_HINT_TEXT \
-       _("If you meant to create a worktree containing a new orphan branch\n" \
+       _("If you meant to create a worktree containing a new unborn branch\n" \
        "(branch with no commits) for this repository, you can do so\n" \
        "using the --orphan flag:\n" \
        "\n" \
@@ -784,7 +784,7 @@ static int add(int ac, const char **av, const char *prefix)
                           N_("create a new branch")),
                OPT_STRING('B', NULL, &new_branch_force, N_("branch"),
                           N_("create or reset a branch")),
-               OPT_BOOL(0, "orphan", &opts.orphan, N_("create unborn/orphaned branch")),
+               OPT_BOOL(0, "orphan", &opts.orphan, N_("create unborn branch")),
                OPT_BOOL('d', "detach", &opts.detach, N_("detach HEAD at named commit")),
                OPT_BOOL(0, "checkout", &opts.checkout, N_("populate the new working tree")),
                OPT_BOOL(0, "lock", &keep_locked, N_("keep the new working tree locked")),

diff --git a/t/t2400-worktree-add.sh b/t/t2400-worktree-add.sh
index b7b667270a389e709509f619a63726608a19182b..3742971105c15268a3c8c41642ff98a75be4f1bf 100755 (executable)
--- a/t/t2400-worktree-add.sh
+++ b/t/t2400-worktree-add.sh
@@ -437,7 +437,7 @@ test_wt_add_orphan_hint () {
                git -C repo switch --orphan noref &&
                test_must_fail git -C repo worktree add $opts foobar/ 2>actual &&
                ! grep "error: unknown switch" actual &&
-               grep "hint: If you meant to create a worktree containing a new orphan branch" actual &&
+               grep "hint: If you meant to create a worktree containing a new unborn branch" actual &&
                if [ $use_branch -eq 1 ]
                then
                        grep -E "^hint: +git worktree add --orphan -b [^ ]+ [^ ]+$" actual
@@ -458,7 +458,7 @@ test_expect_success "'worktree add' doesn't show orphan hint in bad/orphan HEAD
        (cd repo && test_commit commit) &&
        test_must_fail git -C repo worktree add --quiet foobar_branch foobar/ 2>actual &&
        ! grep "error: unknown switch" actual &&
-       ! grep "hint: If you meant to create a worktree containing a new orphan branch" actual
+       ! grep "hint: If you meant to create a worktree containing a new unborn branch" actual
 '
 
 test_expect_success 'local clone from linked checkout' '
@@ -731,7 +731,7 @@ test_expect_success 'git worktree --no-guess-remote option overrides config' '
 test_dwim_orphan () {
        local info_text="No possible source branch, inferring '--orphan'" &&
        local fetch_error_text="fatal: No local or remote refs exist despite at least one remote" &&
-       local orphan_hint="hint: If you meant to create a worktree containing a new orphan branch" &&
+       local orphan_hint="hint: If you meant to create a worktree containing a new unborn branch" &&
        local invalid_ref_regex="^fatal: invalid reference: " &&
        local bad_combo_regex="^fatal: options '[-a-z]*' and '[-a-z]*' cannot be used together" &&