mirror of
https://github.com/git/git.git
synced 2024-05-27 01:46:34 +02:00
Merge branch 'sa/doc-ls-remote' into next
Doc update. * sa/doc-ls-remote: ls-remote doc: document the output format ls-remote doc: explain what each example does ls-remote doc: show peeled tags in examples ls-remote doc: remove redundant --tags example show-branch doc: say <ref>, not <reference> show-ref doc: update for internal consistency
This commit is contained in:
Junio C Hamano
commit
d577bf75a0
|
|
@ -96,27 +96,51 @@ 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^{}
|
||||
----
|
||||
$ 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
|
||||
|
||||
* 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\*
|
||||
d6602ec5194c87b0fc87103ca4d67251c76f233a refs/tags/v0.99
|
||||
f25a265a342aed6041ab0cc484224d9ca54b6f41 refs/tags/v0.99.1
|
||||
c5db5456ae3b0873fc659c19fafdde22313cc441 refs/tags/v0.99.2
|
||||
7ceca275d047c90c0c7d5afb13ab97efdf51bd6e refs/tags/v0.99.3
|
||||
* 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
|
||||
73876f4861cd3d187a4682290ab75c9dccadbc56 refs/tags/v2.40.0^{}
|
||||
----
|
||||
|
||||
SEE ALSO
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
-----------------------------------------------------------------------------
|
||||
|
|
|
|||
Loading…
Reference in New Issue