@matheusbsbs / matheus-bagliano / commits / 622ef9df19
Fork 0

ref-format documentation.

Signed-off-by: Junio C Hamano <junkio@cox.net>

Junio C Hamano committed Oct 16, 2005 at 22:41 UTC 622ef9df199cdbc11ff30e1d92324c1abe3f89cb
3 files changed +66 -2
.gitignore
+1
@@ -8,6 +8,7 @@ git-archimport
8 git-bisect
9 git-branch
10 git-cat-file
11 +git-check-ref-format
12 git-checkout
13 git-checkout-index
14 git-cherry
Documentation/git-check-ref-format.txt new
+50
@@ -0,0 +1,50 @@
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 +'git-check-ref-format' <refname>
11 +
12 +DESCRIPTION
13 +-----------
14 +Checks if a given 'refname' is acceptable, and exits non-zero if
15 +it is not.
16 +
17 +A reference is used in git to specify branches and tags. A
18 +branch head is stored under `$GIT_DIR/refs/heads` directory, and
19 +a tag is stored under `$GIT_DIR/refs/tags` directory. git
20 +imposes the following rules on how refs are named:
21 +
22 +. It could be named hierarchically (i.e. separated with slash
23 + `/`), but each of its component cannot begin with a dot `.`;
24 +
25 +. It cannot have two consecutive dots `..` anywhere;
26 +
27 +. It cannot have ASCII control character (i.e. bytes whose
28 + values are lower than \040, or \177 `DEL`), space, tilde `~`,
29 + caret `{caret}`, or colon `:` anywhere;
30 +
31 +. It cannot end with a slash `/`.
32 +
33 +These rules makes it easy for shell script based tools to parse
34 +refnames, and also avoids ambiguities in certain refname
35 +expressions (see gitlink:git-rev-parse[1]). Namely:
36 +
37 +. double-dot `..` are often used as in `ref1..ref2`, and in some
38 + context this notation means `{caret}ref1 ref2` (i.e. not in
39 + ref1 and in ref2).
40 +
41 +. tilde `~` and caret `{caret}` are used to introduce postfix
42 + 'nth parent' and 'peel onion' operation.
43 +
44 +. colon `:` is used as in `srcref:dstref` to mean "use srcref\'s
45 + value and store it in dstref" in fetch and push operations.
46 +
47 +
48 +GIT
49 +---
50 +Part of the gitlink:git[7] suite
Documentation/git-rev-parse.txt
+15 -2
@@ -79,8 +79,9 @@ OPTIONS
79 SPECIFYING REVISIONS
80 --------------------
81
82 -A revision parameter typically names a commit object. They use
83 -what is called an 'extended SHA1' syntax.
82 +A revision parameter typically, but not necessarily, names a
83 +commit object. They use what is called an 'extended SHA1'
84 +syntax.
85
86 * The full SHA1 object name (40-byte hexadecimal string), or
87 a substring of such that is unique within the repository.
@@ -106,6 +107,18 @@ what is called an 'extended SHA1' syntax.
107 equivalent to rev{caret}{caret}{caret} which is equivalent to\
108 rev{caret}1{caret}1{caret}1.
109
110 +* A suffix '{caret}' followed by an object type name enclosed in
111 + brace pair (e.g. `v0.99.8{caret}\{commit\}`) means the object
112 + could be a tag, and dereference the tag recursively until an
113 + object of that type is found or the object cannot be
114 + dereferenced anymore (in which case, barf). `rev{caret}0`
115 + introduced earlier is a short-hand for `rev{caret}\{commit\}`.
116 +
117 +* A suffix '{caret}' followed by an empty brace pair
118 + (e.g. `v0.99.8{caret}\{\}`) means the object could be a tag,
119 + and dereference the tag recursively until a non-tag object is
120 + found.
121 +
122 'git-rev-parse' also accepts a prefix '{caret}' to revision parameter,
123 which is passed to 'git-rev-list'. Two revision parameters
124 concatenated with '..' is a short-hand for writing a range