{"thread":{"id":"60551","subject":"[PATCH 1/2] orphan/unborn: add to the glossary and use them consistently","startedAt":"2023-11-24T03:09:20Z","lastAt":"2023-12-20T21:22:01Z","messageCount":4,"participants":["Junio C Hamano","Rubén Justo"],"isPatch":true,"patchVersion":1,"patchTotal":2},"messages":[{"id":"485088","messageId":"xmqqbkbj97a9.fsf@gitster.g","threadId":"60551","inReplyTo":null,"subject":"[PATCH 1/2] orphan/unborn: add to the glossary and use them consistently","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-11-24T03:09:18Z","receivedAt":"2023-11-24T03:09:20Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"To orphan is a verb that denotes the act of getting on an unborn\nbranch, and a few references to \"orphan branch\" in our documentation\nare misuses of the word.  They caused end-user confusion, which was\nmade even worse because we did not have the term defined in the\nglossary document.  Add entries for \"unborn\" branch and \"orphan\"\noperation to the glossary, and adjust existing documentation\naccordingly.\n\nSigned-off-by: Junio C Hamano <gitster@pobox.com>\n---\n\n Documentation/config/advice.txt    |  2 +-\n Documentation/git-checkout.txt     |  2 +-\n Documentation/git-switch.txt       |  2 +-\n Documentation/git-worktree.txt     |  4 ++--\n Documentation/glossary-content.txt | 18 ++++++++++++++++++\n 5 files changed, 23 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/config/advice.txt b/Documentation/config/advice.txt\nindex c548a91e67..6aaee01d7f 100644\n--- a/Documentation/config/advice.txt\n+++ b/Documentation/config/advice.txt\n@@ -140,6 +140,6 @@ advice.*::\n \t\tAdvice shown when a fast-forward is not possible.\n \tworktreeAddOrphan::\n \t\tAdvice shown when a user tries to create a worktree from an\n-\t\tinvalid reference, to instruct how to create a new orphan\n+\t\tinvalid reference, to instruct how to create a new unborn\n \t\tbranch instead.\n --\ndiff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\nindex 4af0904f47..3d526613d5 100644\n--- a/Documentation/git-checkout.txt\n+++ b/Documentation/git-checkout.txt\n@@ -213,7 +213,7 @@ variable.\n \tbelow for details.\n \n --orphan <new-branch>::\n-\tCreate a new 'orphan' branch, named `<new-branch>`, started from\n+\tCreate a new unborn branch, named `<new-branch>`, started from\n \t`<start-point>` and switch to it.  The first commit made on this\n \tnew branch will have no parents and it will be the root of a new\n \thistory totally disconnected from all the other branches and\ndiff --git a/Documentation/git-switch.txt b/Documentation/git-switch.txt\nindex c60fc9c138..3e23a82cf2 100644\n--- a/Documentation/git-switch.txt\n+++ b/Documentation/git-switch.txt\n@@ -171,7 +171,7 @@ name, the guessing is aborted.  You can explicitly give a name with\n \t`branch.autoSetupMerge` configuration variable is true.\n \n --orphan <new-branch>::\n-\tCreate a new 'orphan' branch, named `<new-branch>`. All\n+\tCreate a new unborn branch, named `<new-branch>`. All\n \ttracked files are removed.\n \n --ignore-other-worktrees::\ndiff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt\nindex 93d76f5d66..2a240f53ba 100644\n--- a/Documentation/git-worktree.txt\n+++ b/Documentation/git-worktree.txt\n@@ -99,7 +99,7 @@ command will refuse to create the worktree (unless `--force` is used).\n If `<commit-ish>` is omitted, neither `--detach`, or `--orphan` is\n used, and there are no valid local branches (or remote branches if\n `--guess-remote` is specified) then, as a convenience, the new worktree is\n-associated with a new orphan branch named `<branch>` (after\n+associated with a new unborn branch named `<branch>` (after\n `$(basename <path>)` if neither `-b` or `-B` is used) as if `--orphan` was\n passed to the command. In the event the repository has a remote and\n `--guess-remote` is used, but no remote or local branches exist, then the\n@@ -234,7 +234,7 @@ This can also be set up as the default behaviour by using the\n \n --orphan::\n \tWith `add`, make the new worktree and index empty, associating\n-\tthe worktree with a new orphan/unborn branch named `<new-branch>`.\n+\tthe worktree with a new unborn branch named `<new-branch>`.\n \n --porcelain::\n \tWith `list`, output in an easy-to-parse format for scripts.\ndiff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt\nindex 5a537268e2..c67b7f3ec1 100644\n--- a/Documentation/glossary-content.txt\n+++ b/Documentation/glossary-content.txt\n@@ -294,6 +294,12 @@ This commit is referred to as a \"merge commit\", or sometimes just a\n [[def_octopus]]octopus::\n \tTo <<def_merge,merge>> more than two <<def_branch,branches>>.\n \n+[[def_orphan]]orphan::\n+\tThe act of getting on a <<def_branch,branch>> that does not\n+\texist yet (i.e., an <<def_unborn,unborn>> branch).  After\n+\tsuch an operation, the commit first created becomes a commit\n+\twithout a parent, starting a new history.\n+\n [[def_origin]]origin::\n \tThe default upstream <<def_repository,repository>>. Most projects have\n \tat least one upstream project which they track. By default\n@@ -674,6 +680,18 @@ The most notable example is `HEAD`.\n \tobject,\n \tetc.\n \n+[[def_unborn]]unborn::\n+\tThe <<def_HEAD,HEAD>> can point at a <<def_branch,branch>>\n+\tthat does not yet exist and that does not have any commit on\n+\tit yet, and such a branch is called an unborn branch.  The\n+\tmost typical way users encounter an unborn branch is by\n+\tcreating a repository anew without cloning from elsewhere.\n+\tThe HEAD would point at the 'main' (or 'master', depending\n+\ton your configuration) branch that is yet to be born.  Also\n+\tsome operations can get you on an unborn branch with their\n+\t<<def_orphan,orphan>> option.\n+\n+\n [[def_unmerged_index]]unmerged index::\n \tAn <<def_index,index>> which contains unmerged\n \t<<def_index_entry,index entries>>.\n-- \n2.43.0\n\n"},{"id":"485089","messageId":"xmqq4jhb977x.fsf@gitster.g","threadId":"60551","inReplyTo":"xmqqbkbj97a9.fsf@gitster.g","subject":"[PATCH 2/2] orphan/unborn: fix use of 'orphan' in end-user facing messages","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-11-24T03:10:42Z","receivedAt":"2023-11-24T03:10:44Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"orphan branch\" is not even grammatical (\"orphaned branch\" is), and\nwe have been using \"unborn branch\" to mean the state where the HEAD\npoints at a branch that does not yet exist.\n\nUpdate end-user facing messages to correct them.  There are cases\nother random words are used (e.g., \"unparented branch\") but now we\nhave a glossary entry, use the term \"unborn branch\" consistently.\n\nSigned-off-by: Junio C Hamano <gitster@pobox.com>\n---\n builtin/checkout.c      | 2 +-\n builtin/worktree.c      | 6 +++---\n t/t2400-worktree-add.sh | 6 +++---\n 3 files changed, 7 insertions(+), 7 deletions(-)\n\ndiff --git a/builtin/checkout.c b/builtin/checkout.c\nindex f53612f468..9d250587df 100644\n--- a/builtin/checkout.c\n+++ b/builtin/checkout.c\n@@ -1620,7 +1620,7 @@ static struct option *add_common_switch_branch_options(\n \t\t\tparse_opt_tracking_mode),\n \t\tOPT__FORCE(&opts->force, N_(\"force checkout (throw away local modifications)\"),\n \t\t\t   PARSE_OPT_NOCOMPLETE),\n-\t\tOPT_STRING(0, \"orphan\", &opts->new_orphan_branch, N_(\"new-branch\"), N_(\"new unparented branch\")),\n+\t\tOPT_STRING(0, \"orphan\", &opts->new_orphan_branch, N_(\"new-branch\"), N_(\"new unborn branch\")),\n \t\tOPT_BOOL_F(0, \"overwrite-ignore\", &opts->overwrite_ignore,\n \t\t\t   N_(\"update ignored files (default)\"),\n \t\t\t   PARSE_OPT_NOCOMPLETE),\ndiff --git a/builtin/worktree.c b/builtin/worktree.c\nindex 10db70b7ec..f0853a9927 100644\n--- a/builtin/worktree.c\n+++ b/builtin/worktree.c\n@@ -49,14 +49,14 @@\n \t_(\"No possible source branch, inferring '--orphan'\")\n \n #define WORKTREE_ADD_ORPHAN_WITH_DASH_B_HINT_TEXT \\\n-\t_(\"If you meant to create a worktree containing a new orphan branch\\n\" \\\n+\t_(\"If you meant to create a worktree containing a new unborn branch\\n\" \\\n \t\"(branch with no commits) for this repository, you can do so\\n\" \\\n \t\"using the --orphan flag:\\n\" \\\n \t\"\\n\" \\\n \t\"    git worktree add --orphan -b %s %s\\n\")\n \n #define WORKTREE_ADD_ORPHAN_NO_DASH_B_HINT_TEXT \\\n-\t_(\"If you meant to create a worktree containing a new orphan branch\\n\" \\\n+\t_(\"If you meant to create a worktree containing a new unborn branch\\n\" \\\n \t\"(branch with no commits) for this repository, you can do so\\n\" \\\n \t\"using the --orphan flag:\\n\" \\\n \t\"\\n\" \\\n@@ -784,7 +784,7 @@ static int add(int ac, const char **av, const char *prefix)\n \t\t\t   N_(\"create a new branch\")),\n \t\tOPT_STRING('B', NULL, &new_branch_force, N_(\"branch\"),\n \t\t\t   N_(\"create or reset a branch\")),\n-\t\tOPT_BOOL(0, \"orphan\", &opts.orphan, N_(\"create unborn/orphaned branch\")),\n+\t\tOPT_BOOL(0, \"orphan\", &opts.orphan, N_(\"create unborn branch\")),\n \t\tOPT_BOOL('d', \"detach\", &opts.detach, N_(\"detach HEAD at named commit\")),\n \t\tOPT_BOOL(0, \"checkout\", &opts.checkout, N_(\"populate the new working tree\")),\n \t\tOPT_BOOL(0, \"lock\", &keep_locked, N_(\"keep the new working tree locked\")),\ndiff --git a/t/t2400-worktree-add.sh b/t/t2400-worktree-add.sh\nindex 051363acbb..3c12c3932b 100755\n--- a/t/t2400-worktree-add.sh\n+++ b/t/t2400-worktree-add.sh\n@@ -414,7 +414,7 @@ test_wt_add_orphan_hint () {\n \t\tgit -C repo switch --orphan noref &&\n \t\ttest_must_fail git -C repo worktree add $opts foobar/ 2>actual &&\n \t\t! grep \"error: unknown switch\" actual &&\n-\t\tgrep \"hint: If you meant to create a worktree containing a new orphan branch\" actual &&\n+\t\tgrep \"hint: If you meant to create a worktree containing a new unborn branch\" actual &&\n \t\tif [ $use_branch -eq 1 ]\n \t\tthen\n \t\t\tgrep -E \"^hint: +git worktree add --orphan -b [^ ]+ [^ ]+$\" actual\n@@ -435,7 +435,7 @@ test_expect_success \"'worktree add' doesn't show orphan hint in bad/orphan HEAD\n \t(cd repo && test_commit commit) &&\n \ttest_must_fail git -C repo worktree add --quiet foobar_branch foobar/ 2>actual &&\n \t! grep \"error: unknown switch\" actual &&\n-\t! grep \"hint: If you meant to create a worktree containing a new orphan branch\" actual\n+\t! grep \"hint: If you meant to create a worktree containing a new unborn branch\" actual\n '\n \n test_expect_success 'local clone from linked checkout' '\n@@ -708,7 +708,7 @@ test_expect_success 'git worktree --no-guess-remote option overrides config' '\n test_dwim_orphan () {\n \tlocal info_text=\"No possible source branch, inferring '--orphan'\" &&\n \tlocal fetch_error_text=\"fatal: No local or remote refs exist despite at least one remote\" &&\n-\tlocal orphan_hint=\"hint: If you meant to create a worktree containing a new orphan branch\" &&\n+\tlocal orphan_hint=\"hint: If you meant to create a worktree containing a new unborn branch\" &&\n \tlocal invalid_ref_regex=\"^fatal: invalid reference: \" &&\n \tlocal bad_combo_regex=\"^fatal: '[-a-z]*' and '[-a-z]*' cannot be used together\" &&\n \n-- \n2.43.0\n\n"},{"id":"485889","messageId":"xmqqa5q4skwg.fsf@gitster.g","threadId":"60551","inReplyTo":"xmqq4jhb977x.fsf@gitster.g","subject":"Re: [PATCH 2/2] orphan/unborn: fix use of 'orphan' in end-user facing messages","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-12-20T20:01:51Z","receivedAt":"2023-12-20T20:01:57Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"The two-patch series, whose second part is the message I am\nresponding to, did not see much reaction, but since it came\nduring an end-user puzzlement and was written to make the docs less\npuzzling, I am tempted to merge it down to 'next'.\n\nThanks.\n\n"},{"id":"485894","messageId":"8a3b5a71-0207-4129-87b3-e4e3eb7c797b@gmail.com","threadId":"60551","inReplyTo":"xmqqa5q4skwg.fsf@gitster.g","subject":"Re: [PATCH 2/2] orphan/unborn: fix use of 'orphan' in end-user facing messages","fromName":"Rubén Justo","fromEmail":"rjusto@gmail.com","sentAt":"2023-12-20T21:21:58Z","receivedAt":"2023-12-20T21:22:01Z","isPatch":true,"sender":{"key":"rjusto@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5685487?v=4"},"body":"On 20-dic-2023 12:01:51, Junio C Hamano wrote:\n> The two-patch series, whose second part is the message I am\n> responding to, did not see much reaction, but since it came\n> during an end-user puzzlement and was written to make the docs less\n> puzzling, I am tempted to merge it down to 'next'.\n> \n> Thanks.\n> \n\nIf you need some positive feedback;  I've read your series and it looks\ngood to me and going in a good direction.\n\nI think \"unborn branch\" is a more accurate term than \"orphaned branch\".\nIt's not perfect, but I don't have a better one to offer.\n\nA nit in 1/2, which of course is not worth a re-roll, is a double blank\nline near the end;  which I suspect is unintentional.\n\nJust in case anyone else is looking for the thread where the puzzlement\nwas reported:\n\nhttps://lore.kernel.org/git/FE2AD666-88DE-4F70-8D6D-3A426689EB41@me.com/\n\nThank you.\n"}]}