From patchwork Fri Nov 24 03:09:18 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Junio C Hamano X-Patchwork-Id: 13466895 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (1024-bit key) header.d=pobox.com header.i=@pobox.com header.b="idM/xSwN" Received: from pb-smtp2.pobox.com (pb-smtp2.pobox.com [64.147.108.71]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 19E13D43 for ; Thu, 23 Nov 2023 19:09:20 -0800 (PST) Received: from pb-smtp2.pobox.com (unknown [127.0.0.1]) by pb-smtp2.pobox.com (Postfix) with ESMTP id C11031B5A10; Thu, 23 Nov 2023 22:09:19 -0500 (EST) (envelope-from junio@pobox.com) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed; d=pobox.com; h=from:to :subject:date:message-id:mime-version:content-type; s=sasl; bh=m Sv0+KttBvPK4ZSI/eQntyVWwkWxPoELR6qrHiT8qMs=; b=idM/xSwNcygmfRXnF biFo82mgmvVQIHTjEnXyZE7hGPSZVfWHTyu328CXBQLrthZt1iDCseTEk3ALSiAA tSpAGnSkzjUiXrnxXXFUk1uJWG2XMXpxib9jmxaeE42cSf9IONPqX7rzr9/lwTAl SvEPzY210RN7lZbkMPttnbUa7Y= Received: from pb-smtp2.nyi.icgroup.com (unknown [127.0.0.1]) by pb-smtp2.pobox.com (Postfix) with ESMTP id B81DE1B5A0F; Thu, 23 Nov 2023 22:09:19 -0500 (EST) (envelope-from junio@pobox.com) Received: from pobox.com (unknown [34.125.108.217]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by pb-smtp2.pobox.com (Postfix) with ESMTPSA id 211A21B5A0E; Thu, 23 Nov 2023 22:09:19 -0500 (EST) (envelope-from junio@pobox.com) From: Junio C Hamano To: git@vger.kernel.org Subject: [PATCH 1/2] orphan/unborn: add to the glossary and use them consistently Date: Fri, 24 Nov 2023 12:09:18 +0900 Message-ID: User-Agent: Gnus/5.13 (Gnus v5.13) Precedence: bulk X-Mailing-List: git@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 X-Pobox-Relay-ID: DBAEF124-8A76-11EE-9BD8-25B3960A682E-77302942!pb-smtp2.pobox.com 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 --- Documentation/config/advice.txt | 2 +- Documentation/git-checkout.txt | 2 +- Documentation/git-switch.txt | 2 +- Documentation/git-worktree.txt | 4 ++-- Documentation/glossary-content.txt | 18 ++++++++++++++++++ 5 files changed, 23 insertions(+), 5 deletions(-) diff --git a/Documentation/config/advice.txt b/Documentation/config/advice.txt index c548a91e67..6aaee01d7f 100644 --- 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 4af0904f47..3d526613d5 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -213,7 +213,7 @@ variable. below for details. --orphan :: - Create a new 'orphan' branch, named ``, started from + Create a new unborn branch, named ``, started from `` 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 c60fc9c138..3e23a82cf2 100644 --- 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 :: - Create a new 'orphan' branch, named ``. All + Create a new unborn branch, named ``. All tracked files are removed. --ignore-other-worktrees:: diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt index 93d76f5d66..2a240f53ba 100644 --- 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 `` 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 `` (after +associated with a new unborn branch named `` (after `$(basename )` 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 ``. + the worktree with a new unborn branch named ``. --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 5a537268e2..c67b7f3ec1 100644 --- a/Documentation/glossary-content.txt +++ b/Documentation/glossary-content.txt @@ -294,6 +294,12 @@ This commit is referred to as a "merge commit", or sometimes just a [[def_octopus]]octopus:: To <> more than two <>. +[[def_orphan]]orphan:: + The act of getting on a <> that does not + exist yet (i.e., an <> 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 <>. Most projects have at least one upstream project which they track. By default @@ -674,6 +680,18 @@ The most notable example is `HEAD`. object, etc. +[[def_unborn]]unborn:: + The <> can point at a <> + 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 + <> option. + + [[def_unmerged_index]]unmerged index:: An <> which contains unmerged <>. From patchwork Fri Nov 24 03:10:42 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Junio C Hamano X-Patchwork-Id: 13466896 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (1024-bit key) header.d=pobox.com header.i=@pobox.com header.b="Y9RbJnHj" Received: from pb-smtp2.pobox.com (pb-smtp2.pobox.com [64.147.108.71]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 83824D50 for ; Thu, 23 Nov 2023 19:10:44 -0800 (PST) Received: from pb-smtp2.pobox.com (unknown [127.0.0.1]) by pb-smtp2.pobox.com (Postfix) with ESMTP id DE64B1B5A24; Thu, 23 Nov 2023 22:10:43 -0500 (EST) (envelope-from junio@pobox.com) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed; d=pobox.com; h=from:to :subject:in-reply-to:references:date:message-id:mime-version :content-type; s=sasl; bh=rDWu6otsQ9srZk7YXMR011nxSqASA3dIEjNMDQ HXbC4=; b=Y9RbJnHjnbVavcbxD2/zYgY3a5HJJJNb2w5F/0WJhdruuXcSy4FLHC oowGBOxYKdWbgG+f9bGr8p2PCf9OVAfhSweqmNaVn1ufwru2sc7uemoWA+gvsBxZ d/Ez2hiCT2oCy+GpYUlyFST4i2xmrRunAjVbaojh3oc4HK+B4WL/I= Received: from pb-smtp2.nyi.icgroup.com (unknown [127.0.0.1]) by pb-smtp2.pobox.com (Postfix) with ESMTP id D62441B5A22; Thu, 23 Nov 2023 22:10:43 -0500 (EST) (envelope-from junio@pobox.com) Received: from pobox.com (unknown [34.125.108.217]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by pb-smtp2.pobox.com (Postfix) with ESMTPSA id 4BD0F1B5A21; Thu, 23 Nov 2023 22:10:43 -0500 (EST) (envelope-from junio@pobox.com) From: Junio C Hamano To: git@vger.kernel.org Subject: [PATCH 2/2] orphan/unborn: fix use of 'orphan' in end-user facing messages In-Reply-To: (Junio C. Hamano's message of "Fri, 24 Nov 2023 12:09:18 +0900") References: Date: Fri, 24 Nov 2023 12:10:42 +0900 Message-ID: User-Agent: Gnus/5.13 (Gnus v5.13) Precedence: bulk X-Mailing-List: git@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 X-Pobox-Relay-ID: 0DDB7B4A-8A77-11EE-8410-25B3960A682E-77302942!pb-smtp2.pobox.com "orphan branch" is not even grammatical ("orphaned branch" is), and we have been using "unborn branch" to mean the state where the HEAD points at a branch that does not yet exist. Update end-user facing messages to correct them. There are cases other random words are used (e.g., "unparented branch") but now we have a glossary entry, use the term "unborn branch" consistently. Signed-off-by: Junio C Hamano --- builtin/checkout.c | 2 +- builtin/worktree.c | 6 +++--- t/t2400-worktree-add.sh | 6 +++--- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/builtin/checkout.c b/builtin/checkout.c index f53612f468..9d250587df 100644 --- a/builtin/checkout.c +++ b/builtin/checkout.c @@ -1620,7 +1620,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 10db70b7ec..f0853a9927 100644 --- 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 051363acbb..3c12c3932b 100755 --- a/t/t2400-worktree-add.sh +++ b/t/t2400-worktree-add.sh @@ -414,7 +414,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 @@ -435,7 +435,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' ' @@ -708,7 +708,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: '[-a-z]*' and '[-a-z]*' cannot be used together" &&