Re* [PATCH v2 2/2] Document the output format of ls-remote
- From
Junio C Hamano <gitster@pobox.com>
- Date
- Mar 22, 2023, 17:13 UTC
- Message-ID
- <xmqqedpgeml0.fsf_-_@gitster.g>
- In-Reply-To
- <xmqqy1noenq3.fsf@gitster.g>
Junio C Hamano <gitster@pobox.com> writes:
> The documentation for "show-branch" uses many <reference>s in the > description, which should be updated to match what its SYNOPSIS > section uses, which is <ref>.
I forgot to list this in the list of actionable items at the end of my review message I am responding to, so here is a patch to help us not forget about it ;-).
----- >8 ----- Subject: show-branch doc: say <ref>, not <reference>
The glossary defines 'ref' as the official name of the thing, and the output from "git grep -e '<ref' Documentation/" shows that most everybody uses <ref>, not <reference>. In addition, the page already says <ref> in its SYNOPSIS section for the command when it is used in the mode to follow the reflogs.
Strictly speaking, many references of these should be updated to <commit> after adding an explanation on how these <commit>s are discovered (i.e. we take <rev>, <glob>, or <ref> and starting from these commits, follow their ancestry or reflog entries to list commits), but that would be a lot bigger change I would rather not to do in this patch, whose primary purpose is to make the existing documentation more consistent.
Signed-off-by: Junio C Hamano <gitster@pobox.com> --- Documentation/git-show-branch.txt | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-)
diff --git c/Documentation/git-show-branch.txt w/Documentation/git-show-branch.txt index 71f608b1ff..0874c01e37 100644 --- c/Documentation/git-show-branch.txt +++ w/Documentation/git-show-branch.txt @@ -74,8 +74,7 @@ OPTIONS that is the common ancestor of all the branches. This flag tells the command to go <n> more common commits beyond that. When <n> is negative, display only the - <reference>s given, without showing the commit ancestry - tree. + <ref>s given, without showing the commit ancestry tree. --list:: Synonym to `--more=-1` @@ -88,8 +87,8 @@ OPTIONS the case of three or more commits. --independent:: - Among the <reference>s given, display only the ones that - cannot be reached from any other <reference>. + Among the <ref>s given, display only the ones that + cannot be reached from any other <ref>. --no-name:: Do not show naming strings for each commit. @@ -132,7 +131,7 @@ are mutually exclusive. OUTPUT ------ -Given N <references>, the first N lines are the one-line +Given N <ref>s, the first N lines are the one-line description from their commit message. The branch head that is pointed at by $GIT_DIR/HEAD is prefixed with an asterisk `*` character while other heads are prefixed with a `!` character.