1GIT-REV-PARSE(1) Git Manual GIT-REV-PARSE(1)
2
6 git-rev-parse - Pick out and massage parameters
7
9 git-rev-parse [ --option ] <args>...
10
12 Many git porcelainish commands take mixture of flags (i.e. parameters
13 that begin with a dash -) and parameters meant for underlying
14 git-rev-list command they use internally and flags and parameters for
15 other commands they use as the downstream of git-rev-list. This command
16 is used to distinguish between them.
17
19 --revs-only
20 Do not output flags and parameters not meant for git-rev-list
21 command.
22 --no-revs
24 Do not output flags and parameters meant for git-rev-list command.
25 --flags
27 Do not output non-flag parameters.
28 --no-flags
30 Do not output flag parameters.
31 --default <arg>
33 If there is no parameter given by the user, use <arg> instead.
34 --verify
36 The parameter given must be usable as a single, valid object name.
37 Otherwise barf and abort.
38 --sq
40 Usually the output is made one line per flag and parameter. This
41 option makes output a single line, properly quoted for consumption
42 by shell. Useful when you expect your parameter to contain
43 whitespaces and newlines (e.g. when using pickaxe -S with
44 git-diff-*).
45 --not
47 When showing object names, prefix them with ^ and strip ^ prefix
48 from the object names that already have one.
49 --symbolic
51 Usually the object names are output in SHA1 form (with possible ^
52 prefix); this option makes them output in a form as close to the
53 original input as possible.
54 --all
56 Show all refs found in $GIT_DIR/refs.
57 --branches
59 Show branch refs found in $GIT_DIR/refs/heads.
60 --tags
62 Show tag refs found in $GIT_DIR/refs/tags.
63 --remotes
65 Show tag refs found in $GIT_DIR/refs/remotes.
66 --show-prefix
68 When the command is invoked from a subdirectory, show the path of
69 the current directory relative to the top-level directory.
70 --show-cdup
72 When the command is invoked from a subdirectory, show the path of
73 the top-level directory relative to the current directory
74 (typically a sequence of "../", or an empty string).
75 --git-dir
77 Show $GIT_DIR if defined else show the path to the .git directory.
78 --is-inside-git-dir
80 When the current working directory is below the repository
81 directory print "true", otherwise "false".
82 --is-inside-work-tree
84 When the current working directory is inside the work tree of the
85 repository print "true", otherwise "false".
86 --is-bare-repository
88 When the repository is bare print "true", otherwise "false".
89 --short, --short=number
91 Instead of outputting the full SHA1 values of object names try to
92 abbreviate them to a shorter unique name. When no length is
93 specified 7 is used. The minimum length is 4.
94 --since=datestring, --after=datestring
96 Parses the date string, and outputs corresponding --max-age=
97 parameter for git-rev-list command.
98 --until=datestring, --before=datestring
100 Parses the date string, and outputs corresponding --min-age=
101 parameter for git-rev-list command.
102 <args>...
104 Flags and parameters to be parsed.
105
107 A revision parameter typically, but not necessarily, names a commit
108 object. They use what is called an extended SHA1 syntax. Here are
109 various ways to spell object names. The ones listed near the end of
110 this list are to name trees and blobs contained in a commit.
111 · The full SHA1 object name (40-byte hexadecimal string), or a
114 substring of such that is unique within the repository. E.g.
115 dae86e1950b1277e545cee180551750029cfe735 and dae86e both name the
116 same commit object if there are no other object in your repository
117 whose object name starts with dae86e.
118 · An output from git-describe; i.e. a closest tag, followed by a
120 dash, a g, and an abbreviated object name.
121 · A symbolic ref name. E.g. master typically means the commit object
123 referenced by $GIT_DIR/refs/heads/master. If you happen to have
124 both heads/master and tags/master, you can explicitly say
125 heads/master to tell git which one you mean. When ambiguous, a
126 <name> is disambiguated by taking the first match in the following
127 rules:
128 1. if $GIT_DIR/<name> exists, that is what you mean (this is
131 usually useful only for HEAD, FETCH_HEAD and MERGE_HEAD);
132 2. otherwise, $GIT_DIR/refs/<name> if exists;
134 3. otherwise, $GIT_DIR/refs/tags/<name> if exists;
136 4. otherwise, $GIT_DIR/refs/heads/<name> if exists;
138 5. otherwise, $GIT_DIR/refs/remotes/<name> if exists;
140 6. otherwise, $GIT_DIR/refs/remotes/<name>/HEAD if exists.
142 · A ref followed by the suffix @ with a date specification enclosed
144 in a brace pair (e.g. {yesterday}, {1 month 2 weeks 3 days 1 hour 1
145 second ago} or {1979-02-26 18:30:00}) to specify the value of the
146 ref at a prior point in time. This suffix may only be used
147 immediately following a ref name and the ref must have an existing
148 log ($GIT_DIR/logs/<ref>).
149 · A ref followed by the suffix @ with an ordinal specification
151 enclosed in a brace pair (e.g. {1}, {15}) to specify the n-th prior
152 value of that ref. For example master@{1} is the immediate prior
153 value of master while master@{5} is the 5th prior value of master.
154 This suffix may only be used immediately following a ref name and
155 the ref must have an existing log ($GIT_DIR/logs/<ref>).
156 · You can use the @ construct with an empty ref part to get at a
158 reflog of the current branch. For example, if you are on the branch
159 blabla, then @{1} means the same as blabla@{1}.
160 · A suffix ^ to a revision parameter means the first parent of that
162 commit object. ^<n> means the <n>th parent (i.e. rev^ is equivalent
163 to rev^1). As a special rule, rev^0 means the commit itself and is
164 used when rev is the object name of a tag object that refers to a
165 commit object.
166 · A suffix ~<n> to a revision parameter means the commit object that
168 is the <n>th generation grand-parent of the named commit object,
169 following only the first parent. I.e. rev~3 is equivalent to rev^^^
170 which is equivalent to rev^1^1^1. See below for a illustration of
171 the usage of this form.
172 · A suffix ^ followed by an object type name enclosed in brace pair
174 (e.g. v0.99.8^{commit}) means the object could be a tag, and
175 dereference the tag recursively until an object of that type is
176 found or the object cannot be dereferenced anymore (in which case,
177 barf). rev^0 introduced earlier is a short-hand for rev^{commit}.
178 · A suffix ^ followed by an empty brace pair (e.g. v0.99.8^{}) means
180 the object could be a tag, and dereference the tag recursively
181 until a non-tag object is found.
182 · A colon, followed by a slash, followed by a text: this names a
184 commit whose commit message starts with the specified text. This
185 name returns the youngest matching commit which is reachable from
186 any ref. If the commit message starts with a !, you have to repeat
187 that; the special sequence :/!, followed by something else than !
188 is reserved for now.
189 · A suffix : followed by a path; this names the blob or tree at the
191 given path in the tree-ish object named by the part before the
192 colon.
193 · A colon, optionally followed by a stage number (0 to 3) and a
195 colon, followed by a path; this names a blob object in the index at
196 the given path. Missing stage number (and the colon that follows
197 it) names an stage 0 entry. During a merge, stage 1 is the common
198 ancestor, stage 2 is the target branch´s version (typically the
199 current branch), and stage 3 is the version from the branch being
200 merged.
201 Here is an illustration, by Jon Loeliger. Both node B and C are a
202 commit parents of commit node A. Parent commits are ordered
203 left-to-right.
204 G H I J
207 \ / \ /
208 D E F
209 \ | / \
210 \ | / |
211 \|/ |
212 B C
213 \ /
214 \ /
215 A
216 A = = A^0
218 B = A^ = A^1 = A~1
219 C = A^2 = A^2
220 D = A^^ = A^1^1 = A~2
221 E = B^2 = A^^2
222 F = B^3 = A^^3
223 G = A^^^ = A^1^1^1 = A~3
224 H = D^2 = B^^2 = A^^^2 = A~2^2
225 I = F^ = B^3^ = A^^3^
226 J = F^2 = B^3^2 = A^^3^2
227
229 History traversing commands such as git-log operate on a set of
230 commits, not just a single commit. To these commands, specifying a
231 single revision with the notation described in the previous section
232 means the set of commits reachable from that commit, following the
233 commit ancestry chain.
234 To exclude commits reachable from a commit, a prefix ^ notation is
236 used. E.g. "^r1 r2" means commits reachable from r2 but exclude the
237 ones reachable from r1.
238 This set operation appears so often that there is a shorthand for it.
240 "r1..r2" is equivalent to "^r1 r2". It is the difference of two sets
241 (subtract the set of commits reachable from r1 from the set of commits
242 reachable from r2).
243 A similar notation "r1...r2" is called symmetric difference of r1 and
245 r2 and is defined as "r1 r2 --not $(git-merge-base --all r1 r2)". It is
246 the set of commits that are reachable from either one of r1 or r2 but
247 not from both.
248 Two other shorthands for naming a set that is formed by a commit and
250 its parent commits exists. r1^@ notation means all parents of r1. r1^!
251 includes commit r1 but excludes its all parents.
252 Here are a handful examples:
254 D G H D
257 D F G H I J D F
258 ^G D H D
259 ^D B E I J F B
260 B...C G H D E B C
261 ^D B C E I J F B C
262 C^@ I J F
263 F^! D G H D F
264
266 Written by Linus Torvalds <torvalds@osdl.org> and Junio C Hamano
267 <junkio@cox.net>
268
270 Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
271
273 Part of the git(7) suite
274Git 1.5.3.3 10/09/2007 GIT-REV-PARSE(1)