undef/git-commit-vandalism
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Doc/check-ref-format: clarify information about @{-N} syntax

Browse Source 
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:
Kaartic Sivaraam 2017-12-16 13:43:49 +05:30 committed by Junio C Hamano
parent 52015aaf9d
commit c6342e0525
1 changed files with 12 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
Documentation/git-check-ref-format.txt
View File

@ -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}