[PATCH v4 2/2] Doc/check-ref-format: clarify information about @{-N} syntax
- From
Kaartic Sivaraam <kaartic.sivaraam@gmail.com>
- Date
- Dec 14, 2017, 12:30 UTC
- Message-ID
- <20171214123027.9105-1-kaartic.sivaraam@gmail.com>
- In-Reply-To
- <xmqq609olg1p.fsf@gitster.mtv.corp.google.com>
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> ---
Changes in v4:
- updated the commit message - made changes suggested by Junio
Documentation/git-check-ref-format.txt | 28 ++++++++++++++++------------ 1 file changed, 16 insertions(+), 12 deletions(-)
diff --git a/Documentation/git-check-ref-format.txt b/Documentation/git-check-ref-format.txt index cf0a0b7df..8172a6b9a 100644 --- a/Documentation/git-check-ref-format.txt +++ b/Documentation/git-check-ref-format.txt @@ -78,17 +78,21 @@ reference name expressions (see linkgit:gitrevisions[7]): . at-open-brace `@{` is used as a notation to access a reflog entry. 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 -branch). The rule `git check-ref-format --branch $name` implements -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, -but it is explicitly forbidden at the beginning of a branch name). -When run with `--branch` option in a repository, the input is first -expanded for the ``previous branch syntax'' -`@{-n}`. For example, `@{-1}` is a way to refer the last branch you -were on. This option should be used by porcelains to accept this -syntax anywhere a branch name is expected, so they can act as if you -typed the branch name. +it can be used as a valid branch name e.g. when creating a new branch +(but be cautious when using the previous checkout syntax; it 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` 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). When run with `--branch` option in a repository, the +input is first expanded for the ``previous checkout syntax'' +`@{-n}`. For example, `@{-1}` is a way to refer the last thing that +was checked out using "git checkout" operation. This option should be +used by porcelains to accept this syntax anywhere a branch name is +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 ------- @@ -116,7 +120,7 @@ OPTIONS EXAMPLES -------- -* Print the name of the previous branch: +* Print the name of the previous thing checked out: + ------------ $ git check-ref-format --branch @{-1}
-- 2.15.0.531.g2ccb3012c