Documentation/git-check-ref-format.txt

   1 git-check-ref-format(1)
   2 =======================
   3
   4 NAME
   5 ----
   6 git-check-ref-format - Make sure ref name is well formed
   7
   8 SYNOPSIS
   9 --------
  10 [verse]
  11 'git check-ref-format' <refname>
  12 'git check-ref-format' [--branch] <branchname-shorthand>
  13
  14 DESCRIPTION
  15 -----------
  16 Checks if a given 'refname' is acceptable, and exits non-zero if
  17 it is not.
  18
  19 A reference is used in git to specify branches and tags.  A
  20 branch head is stored under `$GIT_DIR/refs/heads` directory, and
  21 a tag is stored under `$GIT_DIR/refs/tags` directory.  git
  22 imposes the following rules on how refs are named:
  23
  24 . It can include slash `/` for hierarchical (directory)
  25   grouping, but no slash-separated component can begin with a
  26   dot `.`;
  27
  28 . It cannot have two consecutive dots `..` anywhere;
  29
  30 . It cannot have ASCII control character (i.e. bytes whose
  31   values are lower than \040, or \177 `DEL`), space, tilde `~`,
  32   caret `{caret}`, colon `:`, question-mark `?`, asterisk `*`,
  33   or open bracket `[` anywhere;
  34
  35 . They cannot end with a slash `/` nor a dot `.`.
  36
  37 . They cannot contain a sequence `@{`.
  38
  39 These rules makes it easy for shell script based tools to parse
  40 refnames, pathname expansion by the shell when a refname is used
  41 unquoted (by mistake), and also avoids ambiguities in certain
  42 refname expressions (see linkgit:git-rev-parse[1]).  Namely:
  43
  44 . double-dot `..` are often used as in `ref1..ref2`, and in some
  45   context this notation means `{caret}ref1 ref2` (i.e. not in
  46   ref1 and in ref2).
  47
  48 . tilde `~` and caret `{caret}` are used to introduce postfix
  49   'nth parent' and 'peel onion' operation.
  50
  51 . colon `:` is used as in `srcref:dstref` to mean "use srcref\'s
  52   value and store it in dstref" in fetch and push operations.
  53   It may also be used to select a specific object such as with
  54   'git-cat-file': "git cat-file blob v1.3.3:refs.c".
  55
  56 . at-open-brace `@{` is used as a notation to access a reflog entry.
  57
  58 With the `--branch` option, it expands a branch name shorthand and
  59 prints the name of the branch the shorthand refers to.
  60
  61 EXAMPLE
  62 -------
  63
  64 git check-ref-format --branch @{-1}::
  65
  66 Print the name of the previous branch.
  67
  68
  69 GIT
  70 ---
  71 Part of the linkgit:git[1] suite