Skip to content

Commit

Permalink
orphan/unborn: add to the glossary and use them consistently
Browse files Browse the repository at this point in the history
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 <[email protected]>
  • Loading branch information
gitster committed Nov 24, 2023
1 parent 564d025 commit 49dc156
Show file tree
Hide file tree
Showing 5 changed files with 23 additions and 5 deletions.
2 changes: 1 addition & 1 deletion Documentation/config/advice.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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.
--
2 changes: 1 addition & 1 deletion Documentation/git-checkout.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion Documentation/git-switch.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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::
Expand Down
4 changes: 2 additions & 2 deletions Documentation/git-worktree.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down
18 changes: 18 additions & 0 deletions Documentation/glossary-content.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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>>.
Expand Down

0 comments on commit 49dc156

Please sign in to comment.