* [PATCH v3 1/6] show-ref doc: update for internal consistency
2023-05-15 12:13 ` [PATCH v3 0/6] " Sean Allred via GitGitGadget
@ 2023-05-15 12:13 ` Sean Allred via GitGitGadget
2023-05-15 16:58 ` Eric Sunshine
2023-05-15 19:48 ` Junio C Hamano
2023-05-15 12:13 ` [PATCH v3 2/6] show-branch doc: say <ref>, not <reference> Junio C Hamano via GitGitGadget
` (5 subsequent siblings)
6 siblings, 2 replies; 33+ messages in thread
From: Sean Allred via GitGitGadget @ 2023-05-15 12:13 UTC (permalink / raw)
To: git; +Cc: Eric Sunshine, Sean Allred, Sean Allred, Sean Allred
From: Sean Allred <allred.sean@gmail.com>
- Use inline-code syntax for options where appropriate.
- Use code blocks to clarify output format.
This patch also swaps out 'SHA-1' language for the implementation-
agnostic 'OID' term where appropriate in preparation for supporting
different hashing algorithms.
Signed-off-by: Sean Allred <allred.sean@gmail.com>
---
Documentation/git-show-ref.txt | 40 ++++++++++++++++++++++------------
1 file changed, 26 insertions(+), 14 deletions(-)
diff --git a/Documentation/git-show-ref.txt b/Documentation/git-show-ref.txt
index d1d56f68b43..be048bf1816 100644
--- a/Documentation/git-show-ref.txt
+++ b/Documentation/git-show-ref.txt
@@ -23,7 +23,7 @@ particular ref exists.
By default, shows the tags, heads, and remote refs.
-The --exclude-existing form is a filter that does the inverse. It reads
+The `--exclude-existing` form is a filter that does the inverse. It reads
refs from stdin, one ref per line, and shows those that don't exist in
the local repository.
@@ -47,14 +47,14 @@ OPTIONS
-d::
--dereference::
- Dereference tags into object IDs as well. They will be shown with "{caret}{}"
+ Dereference tags into object IDs as well. They will be shown with `{caret}{}`
appended.
-s::
--hash[=<n>]::
- Only show the SHA-1 hash, not the reference name. When combined with
- --dereference the dereferenced tag will still be shown after the SHA-1.
+ Only show the OID, not the reference name. When combined with
+ `--dereference`, the dereferenced tag will still be shown after the OID.
--verify::
@@ -70,15 +70,15 @@ OPTIONS
-q::
--quiet::
- Do not print any results to stdout. When combined with `--verify` this
+ Do not print any results to stdout. When combined with `--verify`, this
can be used to silently check if a reference exists.
--exclude-existing[=<pattern>]::
- Make 'git show-ref' act as a filter that reads refs from stdin of the
- form "`^(?:<anything>\s)?<refname>(?:\^{})?$`"
+ Make `git show-ref` act as a filter that reads refs from stdin of the
+ form `^(?:<anything>\s)?<refname>(?:\^{})?$`
and performs the following actions on each:
- (1) strip "{caret}{}" at the end of line if any;
+ (1) strip `{caret}{}` at the end of line if any;
(2) ignore if pattern is provided and does not head-match refname;
(3) warn if refname is not a well-formed refname and skip;
(4) ignore if refname is a ref that exists in the local repository;
@@ -96,7 +96,13 @@ OPTIONS
OUTPUT
------
-The output is in the format: '<SHA-1 ID>' '<space>' '<reference name>'.
+The output is in the format:
+
+------------
+<oid> SP <ref> LF
+------------
+
+For example,
-----------------------------------------------------------------------------
$ git show-ref --head --dereference
@@ -110,7 +116,13 @@ $ git show-ref --head --dereference
...
-----------------------------------------------------------------------------
-When using --hash (and not --dereference) the output format is: '<SHA-1 ID>'
+When using `--hash` (and not `--dereference`), the output is in the format:
+
+------------
+<OID> LF
+------------
+
+For example,
-----------------------------------------------------------------------------
$ git show-ref --heads --hash
@@ -142,10 +154,10 @@ When using the `--verify` flag, the command requires an exact path:
will only match the exact branch called "master".
-If nothing matches, 'git show-ref' will return an error code of 1,
+If nothing matches, `git show-ref` will return an error code of 1,
and in the case of verification, it will show an error message.
-For scripting, you can ask it to be quiet with the "--quiet" flag, which
+For scripting, you can ask it to be quiet with the `--quiet` flag, which
allows you to do things like
-----------------------------------------------------------------------------
@@ -157,11 +169,11 @@ to check whether a particular branch exists or not (notice how we don't
actually want to show any results, and we want to use the full refname for it
in order to not trigger the problem with ambiguous partial matches).
-To show only tags, or only proper branch heads, use "--tags" and/or "--heads"
+To show only tags, or only proper branch heads, use `--tags` and/or `--heads`
respectively (using both means that it shows tags and heads, but not other
random references under the refs/ subdirectory).
-To do automatic tag object dereferencing, use the "-d" or "--dereference"
+To do automatic tag object dereferencing, use the `-d` or `--dereference`
flag, so you can do
-----------------------------------------------------------------------------
--
gitgitgadget
^ permalink raw reply related [flat|nested] 33+ messages in thread* Re: [PATCH v3 1/6] show-ref doc: update for internal consistency
2023-05-15 12:13 ` [PATCH v3 1/6] show-ref doc: update for internal consistency Sean Allred via GitGitGadget
@ 2023-05-15 16:58 ` Eric Sunshine
2023-05-15 17:27 ` Junio C Hamano
2023-05-15 19:48 ` Junio C Hamano
1 sibling, 1 reply; 33+ messages in thread
From: Eric Sunshine @ 2023-05-15 16:58 UTC (permalink / raw)
To: Sean Allred via GitGitGadget; +Cc: git, Sean Allred, Sean Allred
On Mon, May 15, 2023 at 8:13 AM Sean Allred via GitGitGadget
<gitgitgadget@gmail.com> wrote:
> - Use inline-code syntax for options where appropriate.
> - Use code blocks to clarify output format.
>
> This patch also swaps out 'SHA-1' language for the implementation-
> agnostic 'OID' term where appropriate in preparation for supporting
> different hashing algorithms.
>
> Signed-off-by: Sean Allred <allred.sean@gmail.com>
> ---
> diff --git a/Documentation/git-show-ref.txt b/Documentation/git-show-ref.txt
> @@ -96,7 +96,13 @@ OPTIONS
> -The output is in the format: '<SHA-1 ID>' '<space>' '<reference name>'.
> +The output is in the format:
> +
> +------------
> +<oid> SP <ref> LF
> +------------
> $ git show-ref --head --dereference
> @@ -110,7 +116,13 @@ $ git show-ref --head --dereference
> -When using --hash (and not --dereference) the output format is: '<SHA-1 ID>'
> +When using `--hash` (and not `--dereference`), the output is in the format:
> +
> +------------
> +<OID> LF
> +------------
> $ git show-ref --heads --hash
Is the difference in case ("<oid>" vs. "<OID>") intentional between
these two examples?
^ permalink raw reply [flat|nested] 33+ messages in thread* Re: [PATCH v3 1/6] show-ref doc: update for internal consistency
2023-05-15 16:58 ` Eric Sunshine
@ 2023-05-15 17:27 ` Junio C Hamano
2023-05-19 3:51 ` Sean Allred
0 siblings, 1 reply; 33+ messages in thread
From: Junio C Hamano @ 2023-05-15 17:27 UTC (permalink / raw)
To: Eric Sunshine; +Cc: Sean Allred via GitGitGadget, git, Sean Allred, Sean Allred
Eric Sunshine <sunshine@sunshineco.com> writes:
> On Mon, May 15, 2023 at 8:13 AM Sean Allred via GitGitGadget
> <gitgitgadget@gmail.com> wrote:
>> - Use inline-code syntax for options where appropriate.
>> - Use code blocks to clarify output format.
>>
>> This patch also swaps out 'SHA-1' language for the implementation-
>> agnostic 'OID' term where appropriate in preparation for supporting
>> different hashing algorithms.
>>
>> Signed-off-by: Sean Allred <allred.sean@gmail.com>
>> ---
>> diff --git a/Documentation/git-show-ref.txt b/Documentation/git-show-ref.txt
>> @@ -96,7 +96,13 @@ OPTIONS
>> -The output is in the format: '<SHA-1 ID>' '<space>' '<reference name>'.
>> +The output is in the format:
>> +
>> +------------
>> +<oid> SP <ref> LF
>> +------------
>> $ git show-ref --head --dereference
>> @@ -110,7 +116,13 @@ $ git show-ref --head --dereference
>> -When using --hash (and not --dereference) the output format is: '<SHA-1 ID>'
>> +When using `--hash` (and not `--dereference`), the output is in the format:
>> +
>> +------------
>> +<OID> LF
>> +------------
>> $ git show-ref --heads --hash
>
> Is the difference in case ("<oid>" vs. "<OID>") intentional between
> these two examples?
I think it is an incomplete fix based on the suggestion I made for
the previous round,
cf. https://lore.kernel.org/git/xmqqsfdwenn3.fsf@gitster.g/
^ permalink raw reply [flat|nested] 33+ messages in thread* Re: [PATCH v3 1/6] show-ref doc: update for internal consistency
2023-05-15 17:27 ` Junio C Hamano
@ 2023-05-19 3:51 ` Sean Allred
0 siblings, 0 replies; 33+ messages in thread
From: Sean Allred @ 2023-05-19 3:51 UTC (permalink / raw)
To: Junio C Hamano
Cc: Eric Sunshine, Sean Allred via GitGitGadget, git, Sean Allred
Junio C Hamano <gitster@pobox.com> writes:
> Eric Sunshine <sunshine@sunshineco.com> writes:
>
>> On Mon, May 15, 2023 at 8:13 AM Sean Allred via GitGitGadget
>> <gitgitgadget@gmail.com> wrote:
>>> - Use inline-code syntax for options where appropriate.
>>> - Use code blocks to clarify output format.
>>>
>>> This patch also swaps out 'SHA-1' language for the implementation-
>>> agnostic 'OID' term where appropriate in preparation for supporting
>>> different hashing algorithms.
>>>
>>> Signed-off-by: Sean Allred <allred.sean@gmail.com>
>>> ---
>>> diff --git a/Documentation/git-show-ref.txt b/Documentation/git-show-ref.txt
>>> @@ -96,7 +96,13 @@ OPTIONS
>>> -The output is in the format: '<SHA-1 ID>' '<space>' '<reference name>'.
>>> +The output is in the format:
>>> +
>>> +------------
>>> +<oid> SP <ref> LF
>>> +------------
>>> $ git show-ref --head --dereference
>>> @@ -110,7 +116,13 @@ $ git show-ref --head --dereference
>>> -When using --hash (and not --dereference) the output format is: '<SHA-1 ID>'
>>> +When using `--hash` (and not `--dereference`), the output is in the format:
>>> +
>>> +------------
>>> +<OID> LF
>>> +------------
>>> $ git show-ref --heads --hash
>>
>> Is the difference in case ("<oid>" vs. "<OID>") intentional between
>> these two examples?
>
> I think it is an incomplete fix based on the suggestion I made for
> the previous round,
>
> cf. https://lore.kernel.org/git/xmqqsfdwenn3.fsf@gitster.g/
Nice catch; this has been fixed for the next iteration.
--
Sean Allred
^ permalink raw reply [flat|nested] 33+ messages in thread
* Re: [PATCH v3 1/6] show-ref doc: update for internal consistency
2023-05-15 12:13 ` [PATCH v3 1/6] show-ref doc: update for internal consistency Sean Allred via GitGitGadget
2023-05-15 16:58 ` Eric Sunshine
@ 2023-05-15 19:48 ` Junio C Hamano
2023-05-19 3:55 ` Sean Allred
1 sibling, 1 reply; 33+ messages in thread
From: Junio C Hamano @ 2023-05-15 19:48 UTC (permalink / raw)
To: Sean Allred via GitGitGadget; +Cc: git, Eric Sunshine, Sean Allred, Sean Allred
"Sean Allred via GitGitGadget" <gitgitgadget@gmail.com> writes:
> From: Sean Allred <allred.sean@gmail.com>
>
> - Use inline-code syntax for options where appropriate.
> - Use code blocks to clarify output format.
>
> This patch also swaps out 'SHA-1' language for the implementation-
> agnostic 'OID' term where appropriate in preparation for supporting
> different hashing algorithms.
Making the last one into the third bullet item, e.g.
- Use OID instead of SHA-1, as we support different hashing
algorithems these days.
would have been even easier to follow, but I'll let it pass.
In prose, "object name" would flow better than OID (the original
would say not just "SHA-1" but use "SHA-1 hash" or somesuch in such
a context), I would think. When used as a placeholder, OID would be
perfectly fine (<oid>, where we used to write <hash> or <sha-1> or
<SHA-1>).
> -s::
> --hash[=<n>]::
>
> - Only show the SHA-1 hash, not the reference name. When combined with
> - --dereference the dereferenced tag will still be shown after the SHA-1.
> + Only show the OID, not the reference name. When combined with
> + `--dereference`, the dereferenced tag will still be shown after the OID.
Not a problem you created, but I noticed we do not explain what
"=<n>" up there does.
> @@ -96,7 +96,13 @@ OPTIONS
> OUTPUT
> ------
>
> -The output is in the format: '<SHA-1 ID>' '<space>' '<reference name>'.
> +The output is in the format:
> +
> +------------
> +<oid> SP <ref> LF
> +------------
> +
> +For example,
OK.
> @@ -110,7 +116,13 @@ $ git show-ref --head --dereference
> ...
> -----------------------------------------------------------------------------
>
> -When using --hash (and not --dereference) the output format is: '<SHA-1 ID>'
> +When using `--hash` (and not `--dereference`), the output is in the format:
> +
> +------------
> +<OID> LF
> +------------
> +
> +For example,
Let's consistently use <oid> in lowercase as the previous hunk.
Everything else looked great in this step. Thanks for working on this.
^ permalink raw reply [flat|nested] 33+ messages in thread* Re: [PATCH v3 1/6] show-ref doc: update for internal consistency
2023-05-15 19:48 ` Junio C Hamano
@ 2023-05-19 3:55 ` Sean Allred
0 siblings, 0 replies; 33+ messages in thread
From: Sean Allred @ 2023-05-19 3:55 UTC (permalink / raw)
To: Junio C Hamano
Cc: Sean Allred via GitGitGadget, git, Eric Sunshine, Sean Allred,
Sean Allred
Junio C Hamano <gitster@pobox.com> writes:
> Making the last one into the third bullet item, e.g.
>
> - Use OID instead of SHA-1, as we support different hashing
> algorithems these days.
>
> would have been even easier to follow, but I'll let it pass.
Easy enough to change for me; this will be addressed in the next
iteration.
> In prose, "object name" would flow better than OID (the original
> would say not just "SHA-1" but use "SHA-1 hash" or somesuch in such
> a context), I would think. When used as a placeholder, OID would be
> perfectly fine (<oid>, where we used to write <hash> or <sha-1> or
> <SHA-1>).
I've used 'apostrophes' to set off these terms (found as literals in the
documentation that's changed) and explained/expanded 'OID' in the commit
message.
>> -s::
>> --hash[=<n>]::
>>
>> - Only show the SHA-1 hash, not the reference name. When combined with
>> - --dereference the dereferenced tag will still be shown after the SHA-1.
>> + Only show the OID, not the reference name. When combined with
>> + `--dereference`, the dereferenced tag will still be shown after the OID.
>
> Not a problem you created, but I noticed we do not explain what
> "=<n>" up there does.
Given I also don't know what it means, I'll let you spin this off into a
separate bug report however you see fit :-) Just based on the diff
context available above, it's odd to me also that `-s` apparently does
not take an `<n>` -- whatever that may be.
> Everything else looked great in this step. Thanks for working on this.
Always a pleasure :-) Thanks for the review.
--
Sean Allred
^ permalink raw reply [flat|nested] 33+ messages in thread
* [PATCH v3 2/6] show-branch doc: say <ref>, not <reference>
2023-05-15 12:13 ` [PATCH v3 0/6] " Sean Allred via GitGitGadget
2023-05-15 12:13 ` [PATCH v3 1/6] show-ref doc: update for internal consistency Sean Allred via GitGitGadget
@ 2023-05-15 12:13 ` Junio C Hamano via GitGitGadget
2023-05-15 12:13 ` [PATCH v3 3/6] ls-remote doc: remove redundant --tags example Sean Allred via GitGitGadget
` (4 subsequent siblings)
6 siblings, 0 replies; 33+ messages in thread
From: Junio C Hamano via GitGitGadget @ 2023-05-15 12:13 UTC (permalink / raw)
To: git; +Cc: Eric Sunshine, Sean Allred, Sean Allred, Junio C Hamano
From: Junio C Hamano <gitster@pobox.com>
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>
Signed-off-by: Sean Allred <allred.sean@gmail.com>
---
Documentation/git-show-branch.txt | 16 ++++++++--------
1 file changed, 8 insertions(+), 8 deletions(-)
diff --git a/Documentation/git-show-branch.txt b/Documentation/git-show-branch.txt
index 71f608b1ff1..58cf6210cde 100644
--- a/Documentation/git-show-branch.txt
+++ b/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,10 +131,11 @@ are mutually exclusive.
OUTPUT
------
-Given N <references>, 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.
+
+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.
Following these N lines, one-line log for each commit is
displayed, indented N places. If a commit is on the I-th
--
gitgitgadget
^ permalink raw reply related [flat|nested] 33+ messages in thread* [PATCH v3 3/6] ls-remote doc: remove redundant --tags example
2023-05-15 12:13 ` [PATCH v3 0/6] " Sean Allred via GitGitGadget
2023-05-15 12:13 ` [PATCH v3 1/6] show-ref doc: update for internal consistency Sean Allred via GitGitGadget
2023-05-15 12:13 ` [PATCH v3 2/6] show-branch doc: say <ref>, not <reference> Junio C Hamano via GitGitGadget
@ 2023-05-15 12:13 ` Sean Allred via GitGitGadget
2023-05-15 19:52 ` Junio C Hamano
2023-05-15 12:13 ` [PATCH v3 4/6] ls-remote doc: show peeled tags in examples Sean Allred via GitGitGadget
` (3 subsequent siblings)
6 siblings, 1 reply; 33+ messages in thread
From: Sean Allred via GitGitGadget @ 2023-05-15 12:13 UTC (permalink / raw)
To: git; +Cc: Eric Sunshine, Sean Allred, Sean Allred, Sean Allred
From: Sean Allred <allred.sean@gmail.com>
The --tags option is already demonstrated in the later example that
lists version-patterned tags. As it doesn't appear to add anything to
the documentation, it ought to be removed to keep the documentation
easier to read.
Signed-off-by: Sean Allred <allred.sean@gmail.com>
---
Documentation/git-ls-remote.txt | 7 -------
1 file changed, 7 deletions(-)
diff --git a/Documentation/git-ls-remote.txt b/Documentation/git-ls-remote.txt
index ff3da547ddb..af71cf4a92d 100644
--- a/Documentation/git-ls-remote.txt
+++ b/Documentation/git-ls-remote.txt
@@ -100,13 +100,6 @@ EXAMPLES
--------
----
-$ git ls-remote --tags .
-d6602ec5194c87b0fc87103ca4d67251c76f233a refs/tags/v0.99
-f25a265a342aed6041ab0cc484224d9ca54b6f41 refs/tags/v0.99.1
-7ceca275d047c90c0c7d5afb13ab97efdf51bd6e refs/tags/v0.99.3
-c5db5456ae3b0873fc659c19fafdde22313cc441 refs/tags/v0.99.2
-0918385dbd9656cab0d1d81ba7453d49bbc16250 refs/tags/junio-gpg-pub
-
$ git ls-remote http://www.kernel.org/pub/scm/git/git.git master seen rc
5fe978a5381f1fbad26a80e682ddd2a401966740 refs/heads/master
c781a84b5204fb294c9ccc79f8b3baceeb32c061 refs/heads/seen
--
gitgitgadget
^ permalink raw reply related [flat|nested] 33+ messages in thread* Re: [PATCH v3 3/6] ls-remote doc: remove redundant --tags example
2023-05-15 12:13 ` [PATCH v3 3/6] ls-remote doc: remove redundant --tags example Sean Allred via GitGitGadget
@ 2023-05-15 19:52 ` Junio C Hamano
0 siblings, 0 replies; 33+ messages in thread
From: Junio C Hamano @ 2023-05-15 19:52 UTC (permalink / raw)
To: Sean Allred via GitGitGadget; +Cc: git, Eric Sunshine, Sean Allred, Sean Allred
"Sean Allred via GitGitGadget" <gitgitgadget@gmail.com> writes:
> From: Sean Allred <allred.sean@gmail.com>
>
> The --tags option is already demonstrated in the later example that
> lists version-patterned tags. As it doesn't appear to add anything to
> the documentation, it ought to be removed to keep the documentation
> easier to read.
>
> Signed-off-by: Sean Allred <allred.sean@gmail.com>
> ---
> Documentation/git-ls-remote.txt | 7 -------
> 1 file changed, 7 deletions(-)
I like deletions ;-) Thanks.
^ permalink raw reply [flat|nested] 33+ messages in thread
* [PATCH v3 4/6] ls-remote doc: show peeled tags in examples
2023-05-15 12:13 ` [PATCH v3 0/6] " Sean Allred via GitGitGadget
` (2 preceding siblings ...)
2023-05-15 12:13 ` [PATCH v3 3/6] ls-remote doc: remove redundant --tags example Sean Allred via GitGitGadget
@ 2023-05-15 12:13 ` Sean Allred via GitGitGadget
2023-05-15 19:53 ` Junio C Hamano
2023-05-15 12:13 ` [PATCH v3 5/6] ls-remote doc: explain what each example does Sean Allred via GitGitGadget
` (2 subsequent siblings)
6 siblings, 1 reply; 33+ messages in thread
From: Sean Allred via GitGitGadget @ 2023-05-15 12:13 UTC (permalink / raw)
To: git; +Cc: Eric Sunshine, Sean Allred, Sean Allred, Sean Allred
From: Sean Allred <allred.sean@gmail.com>
Without `--refs`, this command will show peeled tags. Make this clearer
in the examples to further mitigate the possibility of surprises in
consuming scripts.
Signed-off-by: Sean Allred <allred.sean@gmail.com>
---
Documentation/git-ls-remote.txt | 8 ++++----
1 file changed, 4 insertions(+), 4 deletions(-)
diff --git a/Documentation/git-ls-remote.txt b/Documentation/git-ls-remote.txt
index af71cf4a92d..aabc1a7b90b 100644
--- a/Documentation/git-ls-remote.txt
+++ b/Documentation/git-ls-remote.txt
@@ -106,10 +106,10 @@ c781a84b5204fb294c9ccc79f8b3baceeb32c061 refs/heads/seen
$ git remote add korg http://www.kernel.org/pub/scm/git/git.git
$ git ls-remote --tags korg v\*
-d6602ec5194c87b0fc87103ca4d67251c76f233a refs/tags/v0.99
-f25a265a342aed6041ab0cc484224d9ca54b6f41 refs/tags/v0.99.1
-c5db5456ae3b0873fc659c19fafdde22313cc441 refs/tags/v0.99.2
-7ceca275d047c90c0c7d5afb13ab97efdf51bd6e refs/tags/v0.99.3
+485a869c64a68cc5795dd99689797c5900f4716d refs/tags/v2.39.2
+cbf04937d5b9fcf0a76c28f69e6294e9e3ecd7e6 refs/tags/v2.39.2^{}
+d4ca2e3147b409459955613c152220f4db848ee1 refs/tags/v2.40.0
+73876f4861cd3d187a4682290ab75c9dccadbc56 refs/tags/v2.40.0^{}
----
SEE ALSO
--
gitgitgadget
^ permalink raw reply related [flat|nested] 33+ messages in thread* Re: [PATCH v3 4/6] ls-remote doc: show peeled tags in examples
2023-05-15 12:13 ` [PATCH v3 4/6] ls-remote doc: show peeled tags in examples Sean Allred via GitGitGadget
@ 2023-05-15 19:53 ` Junio C Hamano
0 siblings, 0 replies; 33+ messages in thread
From: Junio C Hamano @ 2023-05-15 19:53 UTC (permalink / raw)
To: Sean Allred via GitGitGadget; +Cc: git, Eric Sunshine, Sean Allred, Sean Allred
"Sean Allred via GitGitGadget" <gitgitgadget@gmail.com> writes:
> From: Sean Allred <allred.sean@gmail.com>
>
> Without `--refs`, this command will show peeled tags. Make this clearer
> in the examples to further mitigate the possibility of surprises in
> consuming scripts.
>
> Signed-off-by: Sean Allred <allred.sean@gmail.com>
> ---
> Documentation/git-ls-remote.txt | 8 ++++----
> 1 file changed, 4 insertions(+), 4 deletions(-)
Nice attention to the detail. Thanks.
> diff --git a/Documentation/git-ls-remote.txt b/Documentation/git-ls-remote.txt
> index af71cf4a92d..aabc1a7b90b 100644
> --- a/Documentation/git-ls-remote.txt
> +++ b/Documentation/git-ls-remote.txt
> @@ -106,10 +106,10 @@ c781a84b5204fb294c9ccc79f8b3baceeb32c061 refs/heads/seen
>
> $ git remote add korg http://www.kernel.org/pub/scm/git/git.git
> $ git ls-remote --tags korg v\*
> -d6602ec5194c87b0fc87103ca4d67251c76f233a refs/tags/v0.99
> -f25a265a342aed6041ab0cc484224d9ca54b6f41 refs/tags/v0.99.1
> -c5db5456ae3b0873fc659c19fafdde22313cc441 refs/tags/v0.99.2
> -7ceca275d047c90c0c7d5afb13ab97efdf51bd6e refs/tags/v0.99.3
> +485a869c64a68cc5795dd99689797c5900f4716d refs/tags/v2.39.2
> +cbf04937d5b9fcf0a76c28f69e6294e9e3ecd7e6 refs/tags/v2.39.2^{}
> +d4ca2e3147b409459955613c152220f4db848ee1 refs/tags/v2.40.0
> +73876f4861cd3d187a4682290ab75c9dccadbc56 refs/tags/v2.40.0^{}
> ----
>
> SEE ALSO
^ permalink raw reply [flat|nested] 33+ messages in thread
* [PATCH v3 5/6] ls-remote doc: explain what each example does
2023-05-15 12:13 ` [PATCH v3 0/6] " Sean Allred via GitGitGadget
` (3 preceding siblings ...)
2023-05-15 12:13 ` [PATCH v3 4/6] ls-remote doc: show peeled tags in examples Sean Allred via GitGitGadget
@ 2023-05-15 12:13 ` Sean Allred via GitGitGadget
2023-05-15 12:13 ` [PATCH v3 6/6] ls-remote doc: document the output format Sean Allred via GitGitGadget
2023-05-19 4:17 ` [PATCH v4 0/6] Document the output format of ls-remote Sean Allred via GitGitGadget
6 siblings, 0 replies; 33+ messages in thread
From: Sean Allred via GitGitGadget @ 2023-05-15 12:13 UTC (permalink / raw)
To: git; +Cc: Eric Sunshine, Sean Allred, Sean Allred, Sean Allred
From: Sean Allred <allred.sean@gmail.com>
While it's good to have several examples to solidify the output pattern
and generally demonstrate how to use the command, most other EXAMPLES
sections (e.g., git-show-branch.txt, git-remote.txt) additionally
describe the problem/situation to which the example is applicable.
Follow this example in the ls-remote documentation.
Signed-off-by: Sean Allred <allred.sean@gmail.com>
---
Documentation/git-ls-remote.txt | 9 +++++++--
1 file changed, 7 insertions(+), 2 deletions(-)
diff --git a/Documentation/git-ls-remote.txt b/Documentation/git-ls-remote.txt
index aabc1a7b90b..c0b2facef48 100644
--- a/Documentation/git-ls-remote.txt
+++ b/Documentation/git-ls-remote.txt
@@ -99,13 +99,18 @@ OPTIONS
EXAMPLES
--------
+* List all references matching given patterns:
++
----
$ git ls-remote http://www.kernel.org/pub/scm/git/git.git master seen rc
5fe978a5381f1fbad26a80e682ddd2a401966740 refs/heads/master
c781a84b5204fb294c9ccc79f8b3baceeb32c061 refs/heads/seen
+----
-$ git remote add korg http://www.kernel.org/pub/scm/git/git.git
-$ git ls-remote --tags korg v\*
+* List only tags matching a given wildcard pattern:
++
+----
+$ git ls-remote --tags http://www.kernel.org/pub/scm/git/git.git v\*
485a869c64a68cc5795dd99689797c5900f4716d refs/tags/v2.39.2
cbf04937d5b9fcf0a76c28f69e6294e9e3ecd7e6 refs/tags/v2.39.2^{}
d4ca2e3147b409459955613c152220f4db848ee1 refs/tags/v2.40.0
--
gitgitgadget
^ permalink raw reply related [flat|nested] 33+ messages in thread* [PATCH v3 6/6] ls-remote doc: document the output format
2023-05-15 12:13 ` [PATCH v3 0/6] " Sean Allred via GitGitGadget
` (4 preceding siblings ...)
2023-05-15 12:13 ` [PATCH v3 5/6] ls-remote doc: explain what each example does Sean Allred via GitGitGadget
@ 2023-05-15 12:13 ` Sean Allred via GitGitGadget
2023-05-15 20:01 ` Junio C Hamano
2023-05-19 4:17 ` [PATCH v4 0/6] Document the output format of ls-remote Sean Allred via GitGitGadget
6 siblings, 1 reply; 33+ messages in thread
From: Sean Allred via GitGitGadget @ 2023-05-15 12:13 UTC (permalink / raw)
To: git; +Cc: Eric Sunshine, Sean Allred, Sean Allred, Sean Allred
From: Sean Allred <allred.sean@gmail.com>
While well-established, the output format of ls-remote was not actually
documented. This patch adds an OUTPUT section to the documentation
following the format of git-show-ref.txt (which has similar semantics).
Add a basic example immediately after this to solidify the 'normal'
output format.
Signed-off-by: Sean Allred <allred.sean@gmail.com>
---
Documentation/git-ls-remote.txt | 24 ++++++++++++++++++++++++
1 file changed, 24 insertions(+)
diff --git a/Documentation/git-ls-remote.txt b/Documentation/git-ls-remote.txt
index c0b2facef48..15313f2b10d 100644
--- a/Documentation/git-ls-remote.txt
+++ b/Documentation/git-ls-remote.txt
@@ -96,9 +96,33 @@ OPTIONS
separator (so `bar` matches `refs/heads/bar` but not
`refs/heads/foobar`).
+OUTPUT
+------
+
+The output is in the format:
+
+------------
+<oid> TAB <ref> LF
+------------
+
+When `<ref>` is a tag, it may be followed by `^{}` to show its peeled
+representation.
+
EXAMPLES
--------
+* List all references (including symbolics and pseudorefs), peeling
+ tags:
++
+----
+$ git ls-remote
+27d43aaaf50ef0ae014b88bba294f93658016a2e HEAD
+950264636c68591989456e3ba0a5442f93152c1a refs/heads/main
+d9ab777d41f92a8c1684c91cfb02053d7dd1046b refs/heads/next
+d4ca2e3147b409459955613c152220f4db848ee1 refs/tags/v2.40.0
+73876f4861cd3d187a4682290ab75c9dccadbc56 refs/tags/v2.40.0^{}
+----
+
* List all references matching given patterns:
+
----
--
gitgitgadget
^ permalink raw reply related [flat|nested] 33+ messages in thread* Re: [PATCH v3 6/6] ls-remote doc: document the output format
2023-05-15 12:13 ` [PATCH v3 6/6] ls-remote doc: document the output format Sean Allred via GitGitGadget
@ 2023-05-15 20:01 ` Junio C Hamano
2023-05-19 4:04 ` Sean Allred
0 siblings, 1 reply; 33+ messages in thread
From: Junio C Hamano @ 2023-05-15 20:01 UTC (permalink / raw)
To: Sean Allred via GitGitGadget; +Cc: git, Eric Sunshine, Sean Allred, Sean Allred
"Sean Allred via GitGitGadget" <gitgitgadget@gmail.com> writes:
> From: Sean Allred <allred.sean@gmail.com>
>
> While well-established, the output format of ls-remote was not actually
> documented. This patch adds an OUTPUT section to the documentation
> following the format of git-show-ref.txt (which has similar semantics).
>
> Add a basic example immediately after this to solidify the 'normal'
> output format.
>
> Signed-off-by: Sean Allred <allred.sean@gmail.com>
> ---
> Documentation/git-ls-remote.txt | 24 ++++++++++++++++++++++++
> 1 file changed, 24 insertions(+)
>
> diff --git a/Documentation/git-ls-remote.txt b/Documentation/git-ls-remote.txt
> index c0b2facef48..15313f2b10d 100644
> --- a/Documentation/git-ls-remote.txt
> +++ b/Documentation/git-ls-remote.txt
> @@ -96,9 +96,33 @@ OPTIONS
> separator (so `bar` matches `refs/heads/bar` but not
> `refs/heads/foobar`).
>
> +OUTPUT
> +------
> +
> +The output is in the format:
> +
> +------------
> +<oid> TAB <ref> LF
> +------------
> +
> +When `<ref>` is a tag, it may be followed by `^{}` to show its peeled
> +representation.
While I can guess what the above wants to say, the above does not
quite "click" for me for some reason. Here is my attempt.
When showing an annotated tag, unless `--refs` is given, two
such lines are shown, one with the refname for the tag itself as
<ref>, and another with <ref> followed by `^{}`. The `<oid>` on
the latter line shows the name of the object the tag points at.
The verb `peel` is used in the explanation for the `--refs` option,
but there is no formal definition of what it means in the glossary.
We may want to do something about it, but we probably would want to
leave it outside the scope of this series.
Other than that, looking great.
Thanks.
^ permalink raw reply [flat|nested] 33+ messages in thread* Re: [PATCH v3 6/6] ls-remote doc: document the output format
2023-05-15 20:01 ` Junio C Hamano
@ 2023-05-19 4:04 ` Sean Allred
0 siblings, 0 replies; 33+ messages in thread
From: Sean Allred @ 2023-05-19 4:04 UTC (permalink / raw)
To: Junio C Hamano
Cc: Sean Allred via GitGitGadget, git, Eric Sunshine, Sean Allred,
Sean Allred
Junio C Hamano <gitster@pobox.com> writes:
>> +OUTPUT
>> +------
>> +
>> +The output is in the format:
>> +
>> +------------
>> +<oid> TAB <ref> LF
>> +------------
>> +
>> +When `<ref>` is a tag, it may be followed by `^{}` to show its peeled
>> +representation.
>
> While I can guess what the above wants to say, the above does not
> quite "click" for me for some reason. Here is my attempt.
>
> When showing an annotated tag, unless `--refs` is given, two
> such lines are shown, one with the refname for the tag itself as
> <ref>, and another with <ref> followed by `^{}`. The `<oid>` on
> the latter line shows the name of the object the tag points at.
This is clear to me, too (even reading it late at night -- kudos), so
I've adopted your suggestion verbatim with a few minor formatting nits.
Thanks!
> The verb `peel` is used in the explanation for the `--refs` option,
> but there is no formal definition of what it means in the glossary.
>
> We may want to do something about it, but we probably would want to
> leave it outside the scope of this series.
I'll add a tracking task for myself to potentially address this in the
coming week or two, but I'll be happily surprised if someone else beats
me to it :-) I agree it's out of scope for this series.
--
Sean Allred
^ permalink raw reply [flat|nested] 33+ messages in thread
* [PATCH v4 0/6] Document the output format of ls-remote
2023-05-15 12:13 ` [PATCH v3 0/6] " Sean Allred via GitGitGadget
` (5 preceding siblings ...)
2023-05-15 12:13 ` [PATCH v3 6/6] ls-remote doc: document the output format Sean Allred via GitGitGadget
@ 2023-05-19 4:17 ` Sean Allred via GitGitGadget
2023-05-19 4:17 ` [PATCH v4 1/6] show-ref doc: update for internal consistency Sean Allred via GitGitGadget
` (5 more replies)
6 siblings, 6 replies; 33+ messages in thread
From: Sean Allred via GitGitGadget @ 2023-05-19 4:17 UTC (permalink / raw)
To: git; +Cc: Eric Sunshine, Sean Allred, Sean Allred
This iteration incorporates the feedback from v3. A capitalization
inconsistency was fixed and the 'peeled tag' / ^{} discussion in
git-ls-remote.txt was clarified.
Junio C Hamano (1):
show-branch doc: say <ref>, not <reference>
Sean Allred (5):
show-ref doc: update for internal consistency
ls-remote doc: remove redundant --tags example
ls-remote doc: show peeled tags in examples
ls-remote doc: explain what each example does
ls-remote doc: document the output format
Documentation/git-ls-remote.txt | 48 +++++++++++++++++++++++--------
Documentation/git-show-branch.txt | 16 +++++------
Documentation/git-show-ref.txt | 40 +++++++++++++++++---------
3 files changed, 70 insertions(+), 34 deletions(-)
base-commit: 950264636c68591989456e3ba0a5442f93152c1a
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1471%2Fvermiculus%2Fsa%2Fdoc-ls-remote-output-format-v4
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1471/vermiculus/sa/doc-ls-remote-output-format-v4
Pull-Request: https://github.com/git/git/pull/1471
Range-diff vs v3:
1: fe442c2041b ! 1: 49382e81e02 show-ref doc: update for internal consistency
@@ Commit message
- Use inline-code syntax for options where appropriate.
- Use code blocks to clarify output format.
-
- This patch also swaps out 'SHA-1' language for the implementation-
- agnostic 'OID' term where appropriate in preparation for supporting
- different hashing algorithms.
+ - Use 'OID' (for 'object ID') instead of 'SHA-1' as we support
+ different hashing algorithms these days.
Signed-off-by: Sean Allred <allred.sean@gmail.com>
@@ Documentation/git-show-ref.txt: $ git show-ref --head --dereference
+When using `--hash` (and not `--dereference`), the output is in the format:
+
+------------
-+<OID> LF
++<oid> LF
+------------
+
+For example,
2: cd51a70f3ff = 2: ea10e7964a9 show-branch doc: say <ref>, not <reference>
3: 8b644fb1203 = 3: cdd933e6fc3 ls-remote doc: remove redundant --tags example
4: dc0c5ba1751 = 4: 68c35f605ae ls-remote doc: show peeled tags in examples
5: 94380984533 = 5: cfb5dd0e87e ls-remote doc: explain what each example does
6: de57b8aa563 ! 6: 115dba15ce0 ls-remote doc: document the output format
@@ Documentation/git-ls-remote.txt: OPTIONS
+<oid> TAB <ref> LF
+------------
+
-+When `<ref>` is a tag, it may be followed by `^{}` to show its peeled
-+representation.
++When showing an annotated tag, unless `--refs` is given, two such
++lines are shown: one with the refname for the tag itself as `<ref>`,
++and another with `<ref>` followed by `^{}`. The `<oid>` on the latter
++line shows the name of the object the tag points at.
+
EXAMPLES
--------
--
gitgitgadget
^ permalink raw reply [flat|nested] 33+ messages in thread* [PATCH v4 1/6] show-ref doc: update for internal consistency
2023-05-19 4:17 ` [PATCH v4 0/6] Document the output format of ls-remote Sean Allred via GitGitGadget
@ 2023-05-19 4:17 ` Sean Allred via GitGitGadget
2023-05-19 4:17 ` [PATCH v4 2/6] show-branch doc: say <ref>, not <reference> Junio C Hamano via GitGitGadget
` (4 subsequent siblings)
5 siblings, 0 replies; 33+ messages in thread
From: Sean Allred via GitGitGadget @ 2023-05-19 4:17 UTC (permalink / raw)
To: git; +Cc: Eric Sunshine, Sean Allred, Sean Allred, Sean Allred
From: Sean Allred <allred.sean@gmail.com>
- Use inline-code syntax for options where appropriate.
- Use code blocks to clarify output format.
- Use 'OID' (for 'object ID') instead of 'SHA-1' as we support
different hashing algorithms these days.
Signed-off-by: Sean Allred <allred.sean@gmail.com>
---
Documentation/git-show-ref.txt | 40 ++++++++++++++++++++++------------
1 file changed, 26 insertions(+), 14 deletions(-)
diff --git a/Documentation/git-show-ref.txt b/Documentation/git-show-ref.txt
index d1d56f68b43..44c7387d78f 100644
--- a/Documentation/git-show-ref.txt
+++ b/Documentation/git-show-ref.txt
@@ -23,7 +23,7 @@ particular ref exists.
By default, shows the tags, heads, and remote refs.
-The --exclude-existing form is a filter that does the inverse. It reads
+The `--exclude-existing` form is a filter that does the inverse. It reads
refs from stdin, one ref per line, and shows those that don't exist in
the local repository.
@@ -47,14 +47,14 @@ OPTIONS
-d::
--dereference::
- Dereference tags into object IDs as well. They will be shown with "{caret}{}"
+ Dereference tags into object IDs as well. They will be shown with `{caret}{}`
appended.
-s::
--hash[=<n>]::
- Only show the SHA-1 hash, not the reference name. When combined with
- --dereference the dereferenced tag will still be shown after the SHA-1.
+ Only show the OID, not the reference name. When combined with
+ `--dereference`, the dereferenced tag will still be shown after the OID.
--verify::
@@ -70,15 +70,15 @@ OPTIONS
-q::
--quiet::
- Do not print any results to stdout. When combined with `--verify` this
+ Do not print any results to stdout. When combined with `--verify`, this
can be used to silently check if a reference exists.
--exclude-existing[=<pattern>]::
- Make 'git show-ref' act as a filter that reads refs from stdin of the
- form "`^(?:<anything>\s)?<refname>(?:\^{})?$`"
+ Make `git show-ref` act as a filter that reads refs from stdin of the
+ form `^(?:<anything>\s)?<refname>(?:\^{})?$`
and performs the following actions on each:
- (1) strip "{caret}{}" at the end of line if any;
+ (1) strip `{caret}{}` at the end of line if any;
(2) ignore if pattern is provided and does not head-match refname;
(3) warn if refname is not a well-formed refname and skip;
(4) ignore if refname is a ref that exists in the local repository;
@@ -96,7 +96,13 @@ OPTIONS
OUTPUT
------
-The output is in the format: '<SHA-1 ID>' '<space>' '<reference name>'.
+The output is in the format:
+
+------------
+<oid> SP <ref> LF
+------------
+
+For example,
-----------------------------------------------------------------------------
$ git show-ref --head --dereference
@@ -110,7 +116,13 @@ $ git show-ref --head --dereference
...
-----------------------------------------------------------------------------
-When using --hash (and not --dereference) the output format is: '<SHA-1 ID>'
+When using `--hash` (and not `--dereference`), the output is in the format:
+
+------------
+<oid> LF
+------------
+
+For example,
-----------------------------------------------------------------------------
$ git show-ref --heads --hash
@@ -142,10 +154,10 @@ When using the `--verify` flag, the command requires an exact path:
will only match the exact branch called "master".
-If nothing matches, 'git show-ref' will return an error code of 1,
+If nothing matches, `git show-ref` will return an error code of 1,
and in the case of verification, it will show an error message.
-For scripting, you can ask it to be quiet with the "--quiet" flag, which
+For scripting, you can ask it to be quiet with the `--quiet` flag, which
allows you to do things like
-----------------------------------------------------------------------------
@@ -157,11 +169,11 @@ to check whether a particular branch exists or not (notice how we don't
actually want to show any results, and we want to use the full refname for it
in order to not trigger the problem with ambiguous partial matches).
-To show only tags, or only proper branch heads, use "--tags" and/or "--heads"
+To show only tags, or only proper branch heads, use `--tags` and/or `--heads`
respectively (using both means that it shows tags and heads, but not other
random references under the refs/ subdirectory).
-To do automatic tag object dereferencing, use the "-d" or "--dereference"
+To do automatic tag object dereferencing, use the `-d` or `--dereference`
flag, so you can do
-----------------------------------------------------------------------------
--
gitgitgadget
^ permalink raw reply related [flat|nested] 33+ messages in thread* [PATCH v4 2/6] show-branch doc: say <ref>, not <reference>
2023-05-19 4:17 ` [PATCH v4 0/6] Document the output format of ls-remote Sean Allred via GitGitGadget
2023-05-19 4:17 ` [PATCH v4 1/6] show-ref doc: update for internal consistency Sean Allred via GitGitGadget
@ 2023-05-19 4:17 ` Junio C Hamano via GitGitGadget
2023-05-19 4:17 ` [PATCH v4 3/6] ls-remote doc: remove redundant --tags example Sean Allred via GitGitGadget
` (3 subsequent siblings)
5 siblings, 0 replies; 33+ messages in thread
From: Junio C Hamano via GitGitGadget @ 2023-05-19 4:17 UTC (permalink / raw)
To: git; +Cc: Eric Sunshine, Sean Allred, Sean Allred, Junio C Hamano
From: Junio C Hamano <gitster@pobox.com>
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>
Signed-off-by: Sean Allred <allred.sean@gmail.com>
---
Documentation/git-show-branch.txt | 16 ++++++++--------
1 file changed, 8 insertions(+), 8 deletions(-)
diff --git a/Documentation/git-show-branch.txt b/Documentation/git-show-branch.txt
index 71f608b1ff1..58cf6210cde 100644
--- a/Documentation/git-show-branch.txt
+++ b/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,10 +131,11 @@ are mutually exclusive.
OUTPUT
------
-Given N <references>, 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.
+
+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.
Following these N lines, one-line log for each commit is
displayed, indented N places. If a commit is on the I-th
--
gitgitgadget
^ permalink raw reply related [flat|nested] 33+ messages in thread* [PATCH v4 3/6] ls-remote doc: remove redundant --tags example
2023-05-19 4:17 ` [PATCH v4 0/6] Document the output format of ls-remote Sean Allred via GitGitGadget
2023-05-19 4:17 ` [PATCH v4 1/6] show-ref doc: update for internal consistency Sean Allred via GitGitGadget
2023-05-19 4:17 ` [PATCH v4 2/6] show-branch doc: say <ref>, not <reference> Junio C Hamano via GitGitGadget
@ 2023-05-19 4:17 ` Sean Allred via GitGitGadget
2023-05-19 4:17 ` [PATCH v4 4/6] ls-remote doc: show peeled tags in examples Sean Allred via GitGitGadget
` (2 subsequent siblings)
5 siblings, 0 replies; 33+ messages in thread
From: Sean Allred via GitGitGadget @ 2023-05-19 4:17 UTC (permalink / raw)
To: git; +Cc: Eric Sunshine, Sean Allred, Sean Allred, Sean Allred
From: Sean Allred <allred.sean@gmail.com>
The --tags option is already demonstrated in the later example that
lists version-patterned tags. As it doesn't appear to add anything to
the documentation, it ought to be removed to keep the documentation
easier to read.
Signed-off-by: Sean Allred <allred.sean@gmail.com>
---
Documentation/git-ls-remote.txt | 7 -------
1 file changed, 7 deletions(-)
diff --git a/Documentation/git-ls-remote.txt b/Documentation/git-ls-remote.txt
index ff3da547ddb..af71cf4a92d 100644
--- a/Documentation/git-ls-remote.txt
+++ b/Documentation/git-ls-remote.txt
@@ -100,13 +100,6 @@ EXAMPLES
--------
----
-$ git ls-remote --tags .
-d6602ec5194c87b0fc87103ca4d67251c76f233a refs/tags/v0.99
-f25a265a342aed6041ab0cc484224d9ca54b6f41 refs/tags/v0.99.1
-7ceca275d047c90c0c7d5afb13ab97efdf51bd6e refs/tags/v0.99.3
-c5db5456ae3b0873fc659c19fafdde22313cc441 refs/tags/v0.99.2
-0918385dbd9656cab0d1d81ba7453d49bbc16250 refs/tags/junio-gpg-pub
-
$ git ls-remote http://www.kernel.org/pub/scm/git/git.git master seen rc
5fe978a5381f1fbad26a80e682ddd2a401966740 refs/heads/master
c781a84b5204fb294c9ccc79f8b3baceeb32c061 refs/heads/seen
--
gitgitgadget
^ permalink raw reply related [flat|nested] 33+ messages in thread* [PATCH v4 4/6] ls-remote doc: show peeled tags in examples
2023-05-19 4:17 ` [PATCH v4 0/6] Document the output format of ls-remote Sean Allred via GitGitGadget
` (2 preceding siblings ...)
2023-05-19 4:17 ` [PATCH v4 3/6] ls-remote doc: remove redundant --tags example Sean Allred via GitGitGadget
@ 2023-05-19 4:17 ` Sean Allred via GitGitGadget
2023-05-19 4:17 ` [PATCH v4 5/6] ls-remote doc: explain what each example does Sean Allred via GitGitGadget
2023-05-19 4:17 ` [PATCH v4 6/6] ls-remote doc: document the output format Sean Allred via GitGitGadget
5 siblings, 0 replies; 33+ messages in thread
From: Sean Allred via GitGitGadget @ 2023-05-19 4:17 UTC (permalink / raw)
To: git; +Cc: Eric Sunshine, Sean Allred, Sean Allred, Sean Allred
From: Sean Allred <allred.sean@gmail.com>
Without `--refs`, this command will show peeled tags. Make this clearer
in the examples to further mitigate the possibility of surprises in
consuming scripts.
Signed-off-by: Sean Allred <allred.sean@gmail.com>
---
Documentation/git-ls-remote.txt | 8 ++++----
1 file changed, 4 insertions(+), 4 deletions(-)
diff --git a/Documentation/git-ls-remote.txt b/Documentation/git-ls-remote.txt
index af71cf4a92d..aabc1a7b90b 100644
--- a/Documentation/git-ls-remote.txt
+++ b/Documentation/git-ls-remote.txt
@@ -106,10 +106,10 @@ c781a84b5204fb294c9ccc79f8b3baceeb32c061 refs/heads/seen
$ git remote add korg http://www.kernel.org/pub/scm/git/git.git
$ git ls-remote --tags korg v\*
-d6602ec5194c87b0fc87103ca4d67251c76f233a refs/tags/v0.99
-f25a265a342aed6041ab0cc484224d9ca54b6f41 refs/tags/v0.99.1
-c5db5456ae3b0873fc659c19fafdde22313cc441 refs/tags/v0.99.2
-7ceca275d047c90c0c7d5afb13ab97efdf51bd6e refs/tags/v0.99.3
+485a869c64a68cc5795dd99689797c5900f4716d refs/tags/v2.39.2
+cbf04937d5b9fcf0a76c28f69e6294e9e3ecd7e6 refs/tags/v2.39.2^{}
+d4ca2e3147b409459955613c152220f4db848ee1 refs/tags/v2.40.0
+73876f4861cd3d187a4682290ab75c9dccadbc56 refs/tags/v2.40.0^{}
----
SEE ALSO
--
gitgitgadget
^ permalink raw reply related [flat|nested] 33+ messages in thread* [PATCH v4 5/6] ls-remote doc: explain what each example does
2023-05-19 4:17 ` [PATCH v4 0/6] Document the output format of ls-remote Sean Allred via GitGitGadget
` (3 preceding siblings ...)
2023-05-19 4:17 ` [PATCH v4 4/6] ls-remote doc: show peeled tags in examples Sean Allred via GitGitGadget
@ 2023-05-19 4:17 ` Sean Allred via GitGitGadget
2023-05-19 4:17 ` [PATCH v4 6/6] ls-remote doc: document the output format Sean Allred via GitGitGadget
5 siblings, 0 replies; 33+ messages in thread
From: Sean Allred via GitGitGadget @ 2023-05-19 4:17 UTC (permalink / raw)
To: git; +Cc: Eric Sunshine, Sean Allred, Sean Allred, Sean Allred
From: Sean Allred <allred.sean@gmail.com>
While it's good to have several examples to solidify the output pattern
and generally demonstrate how to use the command, most other EXAMPLES
sections (e.g., git-show-branch.txt, git-remote.txt) additionally
describe the problem/situation to which the example is applicable.
Follow this example in the ls-remote documentation.
Signed-off-by: Sean Allred <allred.sean@gmail.com>
---
Documentation/git-ls-remote.txt | 9 +++++++--
1 file changed, 7 insertions(+), 2 deletions(-)
diff --git a/Documentation/git-ls-remote.txt b/Documentation/git-ls-remote.txt
index aabc1a7b90b..c0b2facef48 100644
--- a/Documentation/git-ls-remote.txt
+++ b/Documentation/git-ls-remote.txt
@@ -99,13 +99,18 @@ OPTIONS
EXAMPLES
--------
+* List all references matching given patterns:
++
----
$ git ls-remote http://www.kernel.org/pub/scm/git/git.git master seen rc
5fe978a5381f1fbad26a80e682ddd2a401966740 refs/heads/master
c781a84b5204fb294c9ccc79f8b3baceeb32c061 refs/heads/seen
+----
-$ git remote add korg http://www.kernel.org/pub/scm/git/git.git
-$ git ls-remote --tags korg v\*
+* List only tags matching a given wildcard pattern:
++
+----
+$ git ls-remote --tags http://www.kernel.org/pub/scm/git/git.git v\*
485a869c64a68cc5795dd99689797c5900f4716d refs/tags/v2.39.2
cbf04937d5b9fcf0a76c28f69e6294e9e3ecd7e6 refs/tags/v2.39.2^{}
d4ca2e3147b409459955613c152220f4db848ee1 refs/tags/v2.40.0
--
gitgitgadget
^ permalink raw reply related [flat|nested] 33+ messages in thread* [PATCH v4 6/6] ls-remote doc: document the output format
2023-05-19 4:17 ` [PATCH v4 0/6] Document the output format of ls-remote Sean Allred via GitGitGadget
` (4 preceding siblings ...)
2023-05-19 4:17 ` [PATCH v4 5/6] ls-remote doc: explain what each example does Sean Allred via GitGitGadget
@ 2023-05-19 4:17 ` Sean Allred via GitGitGadget
5 siblings, 0 replies; 33+ messages in thread
From: Sean Allred via GitGitGadget @ 2023-05-19 4:17 UTC (permalink / raw)
To: git; +Cc: Eric Sunshine, Sean Allred, Sean Allred, Sean Allred
From: Sean Allred <allred.sean@gmail.com>
While well-established, the output format of ls-remote was not actually
documented. This patch adds an OUTPUT section to the documentation
following the format of git-show-ref.txt (which has similar semantics).
Add a basic example immediately after this to solidify the 'normal'
output format.
Signed-off-by: Sean Allred <allred.sean@gmail.com>
---
Documentation/git-ls-remote.txt | 26 ++++++++++++++++++++++++++
1 file changed, 26 insertions(+)
diff --git a/Documentation/git-ls-remote.txt b/Documentation/git-ls-remote.txt
index c0b2facef48..1c4f696ab57 100644
--- a/Documentation/git-ls-remote.txt
+++ b/Documentation/git-ls-remote.txt
@@ -96,9 +96,35 @@ OPTIONS
separator (so `bar` matches `refs/heads/bar` but not
`refs/heads/foobar`).
+OUTPUT
+------
+
+The output is in the format:
+
+------------
+<oid> TAB <ref> LF
+------------
+
+When showing an annotated tag, unless `--refs` is given, two such
+lines are shown: one with the refname for the tag itself as `<ref>`,
+and another with `<ref>` followed by `^{}`. The `<oid>` on the latter
+line shows the name of the object the tag points at.
+
EXAMPLES
--------
+* List all references (including symbolics and pseudorefs), peeling
+ tags:
++
+----
+$ git ls-remote
+27d43aaaf50ef0ae014b88bba294f93658016a2e HEAD
+950264636c68591989456e3ba0a5442f93152c1a refs/heads/main
+d9ab777d41f92a8c1684c91cfb02053d7dd1046b refs/heads/next
+d4ca2e3147b409459955613c152220f4db848ee1 refs/tags/v2.40.0
+73876f4861cd3d187a4682290ab75c9dccadbc56 refs/tags/v2.40.0^{}
+----
+
* List all references matching given patterns:
+
----
--
gitgitgadget
^ permalink raw reply related [flat|nested] 33+ messages in thread