[PATCH 3/3] check-ref-format doc: --branch validates and expands <branch>
From: Jonathan Nieder <hidden>
Date: 2017-10-17 07:12:42
Subsystem:
documentation, the rest · Maintainers:
Jonathan Corbet, Linus Torvalds
Possibly related (same subject, not in this thread)
- 2017-10-18 · Re: [PATCH 3/3] check-ref-format doc: --branch validates and expands <branch> · Jeff King <hidden>
- 2017-10-17 · Re: [PATCH 3/3] check-ref-format doc: --branch validates and expands <branch> · Jonathan Nieder <hidden>
- 2017-10-17 · Re: [PATCH 3/3] check-ref-format doc: --branch validates and expands <branch> · Junio C Hamano <hidden>
From: Junio C Hamano <redacted>
"git check-ref-format --branch $name" feature was originally
introduced (and was advertised) as a way for scripts to take any
end-user supplied string (like "master", "@{-1}" etc.) and see if it
is usable when Git expects to see a branch name, and also obtain the
concrete branch name that the at-mark magic expands to.
Emphasize that "see if it is usable" role in the description and
clarify that the @{...} expansion only occurs when run from within a
repository.
[jn: split out from a larger patch]
Helped-by: Jeff King [off-list ref]
Signed-off-by: Junio C Hamano <redacted>
---
Documentation/git-check-ref-format.txt | 9 ++++++++-
1 file changed, 8 insertions(+), 1 deletion(-)
diff --git a/Documentation/git-check-ref-format.txt b/Documentation/git-check-ref-format.txt
index 92777cef25..cf0a0b7df2 100644
--- a/Documentation/git-check-ref-format.txt
+++ b/Documentation/git-check-ref-format.txt@@ -77,7 +77,14 @@ reference name expressions (see linkgit:gitrevisions[7]): . at-open-brace `@{` is used as a notation to access a reflog entry. -With the `--branch` option, it expands the ``previous branch syntax'' +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
--
2.15.0.rc1.287.g2b38de12cc