mirror of
https://github.com/git/git
synced 2024-08-25 02:35:46 +00:00
Doc/check-ref-format: clarify information about @{-N} syntax
When the N-th previous thing checked out syntax (@{-N}) is used with '--branch' option of check-ref-format the result may not be the name of a branch that currently exists or ever existed. This is because @{-N} is used to refer to the N-th last checked out "thing", which might be a commit object name if the previous check out was a detached HEAD state; or a branch name, otherwise. The documentation thus does a wrong thing by promoting it as the "previous branch syntax". State that @{-N} is the syntax for specifying "N-th last thing checked out" and also state that the result of using @{-N} might also result in an commit object name. Signed-off-by: Kaartic Sivaraam <kaartic.sivaraam@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
This commit is contained in:
parent
52015aaf9d
commit
c6342e0525
|
@ -79,16 +79,21 @@ reference name expressions (see linkgit:gitrevisions[7]):
|
||||||
|
|
||||||
With the `--branch` option, the command takes a name and checks if
|
With the `--branch` option, the command takes a name and checks if
|
||||||
it can be used as a valid branch name (e.g. when creating a new
|
it can be used as a valid branch name (e.g. when creating a new
|
||||||
branch). The rule `git check-ref-format --branch $name` implements
|
branch). But be cautious when using the
|
||||||
|
previous checkout syntax that may refer to a detached HEAD state.
|
||||||
|
The rule `git check-ref-format --branch $name` implements
|
||||||
may be stricter than what `git check-ref-format refs/heads/$name`
|
may be stricter than what `git check-ref-format refs/heads/$name`
|
||||||
says (e.g. a dash may appear at the beginning of a ref component,
|
says (e.g. a dash may appear at the beginning of a ref component,
|
||||||
but it is explicitly forbidden at the beginning of a branch name).
|
but it is explicitly forbidden at the beginning of a branch name).
|
||||||
When run with `--branch` option in a repository, the input is first
|
When run with `--branch` option in a repository, the input is first
|
||||||
expanded for the ``previous branch syntax''
|
expanded for the ``previous checkout syntax''
|
||||||
`@{-n}`. For example, `@{-1}` is a way to refer the last branch you
|
`@{-n}`. For example, `@{-1}` is a way to refer the last thing that
|
||||||
were on. This option should be used by porcelains to accept this
|
was checked out using "git checkout" operation. This option should be
|
||||||
syntax anywhere a branch name is expected, so they can act as if you
|
used by porcelains to accept this syntax anywhere a branch name is
|
||||||
typed the branch name.
|
expected, so they can act as if you typed the branch name. As an
|
||||||
|
exception note that, the ``previous checkout operation'' might result
|
||||||
|
in a commit object name when the N-th last thing checked out was not
|
||||||
|
a branch.
|
||||||
|
|
||||||
OPTIONS
|
OPTIONS
|
||||||
-------
|
-------
|
||||||
|
@ -116,7 +121,7 @@ OPTIONS
|
||||||
EXAMPLES
|
EXAMPLES
|
||||||
--------
|
--------
|
||||||
|
|
||||||
* Print the name of the previous branch:
|
* Print the name of the previous thing checked out:
|
||||||
+
|
+
|
||||||
------------
|
------------
|
||||||
$ git check-ref-format --branch @{-1}
|
$ git check-ref-format --branch @{-1}
|
||||||
|
|
Loading…
Reference in a new issue