79
80
With the `--branch` option, the command takes a name and checks if
81
it can be used as a valid branch name (e.g. when creating a new
82
-branch). The rule `git check-ref-format --branch $name` implements
82
+branch). But be cautious when using the
83
+previous checkout syntax that may refer to a detached HEAD state.
84
+The rule `git check-ref-format --branch $name` implements
85
may be stricter than what `git check-ref-format refs/heads/$name`
86
says (e.g. a dash may appear at the beginning of a ref component,
87
but it is explicitly forbidden at the beginning of a branch name).
88
When run with `--branch` option in a repository, the input is first
87
-expanded for the ``previous branch syntax''
88
-`@{-n}`. For example, `@{-1}` is a way to refer the last branch you
89
-were on. This option should be used by porcelains to accept this
90
-syntax anywhere a branch name is expected, so they can act as if you
91
-typed the branch name.
89
+expanded for the ``previous checkout syntax''
90
+`@{-n}`. For example, `@{-1}` is a way to refer the last thing that
91
+was checked out using "git checkout" operation. This option should be
92
+used by porcelains to accept this syntax anywhere a branch name is
93
+expected, so they can act as if you typed the branch name. As an
94
+exception note that, the ``previous checkout operation'' might result
95
+in a commit object name when the N-th last thing checked out was not
96
+a branch.
97
98
OPTIONS
99
-------
121
EXAMPLES
122
--------
123
119
-* Print the name of the previous branch:
124
+* Print the name of the previous thing checked out:
125
+
126
------------
127
$ git check-ref-format --branch @{-1}