5641d995180b7aed563872b2403dbd29870a2185
1 git-rev-parse(1)
2 ================
4 NAME
5 ----
6 git-rev-parse - Pick out and massage parameters
9 SYNOPSIS
10 --------
11 'git-rev-parse' [ --option ] <args>...
13 DESCRIPTION
14 -----------
16 Many git porcelainish commands take mixture of flags
17 (i.e. parameters that begin with a dash '-') and parameters
18 meant for underlying `git-rev-list` command they use internally
19 and flags and parameters for other commands they use as the
20 downstream of `git-rev-list`. This command is used to
21 distinguish between them.
24 OPTIONS
25 -------
26 --parseopt::
27 Use `git-rev-parse` in option parsing mode (see PARSEOPT section below).
29 --keep-dash-dash::
30 Only meaningful in `--parseopt` mode. Tells the option parser to echo
31 out the first `--` met instead of skipping it.
33 --revs-only::
34 Do not output flags and parameters not meant for
35 `git-rev-list` command.
37 --no-revs::
38 Do not output flags and parameters meant for
39 `git-rev-list` command.
41 --flags::
42 Do not output non-flag parameters.
44 --no-flags::
45 Do not output flag parameters.
47 --default <arg>::
48 If there is no parameter given by the user, use `<arg>`
49 instead.
51 --verify::
52 The parameter given must be usable as a single, valid
53 object name. Otherwise barf and abort.
55 -q, --quiet::
56 Only meaningful in `--verify` mode. Do not output an error
57 message if the first argument is not a valid object name;
58 instead exit with non-zero status silently.
60 --sq::
61 Usually the output is made one line per flag and
62 parameter. This option makes output a single line,
63 properly quoted for consumption by shell. Useful when
64 you expect your parameter to contain whitespaces and
65 newlines (e.g. when using pickaxe `-S` with
66 `git-diff-\*`).
68 --not::
69 When showing object names, prefix them with '{caret}' and
70 strip '{caret}' prefix from the object names that already have
71 one.
73 --symbolic::
74 Usually the object names are output in SHA1 form (with
75 possible '{caret}' prefix); this option makes them output in a
76 form as close to the original input as possible.
78 --symbolic-full-name::
79 This is similar to \--symbolic, but it omits input that
80 are not refs (i.e. branch or tag names; or more
81 explicitly disambiguating "heads/master" form, when you
82 want to name the "master" branch when there is an
83 unfortunately named tag "master"), and show them as full
84 refnames (e.g. "refs/heads/master").
86 --all::
87 Show all refs found in `$GIT_DIR/refs`.
89 --branches::
90 Show branch refs found in `$GIT_DIR/refs/heads`.
92 --tags::
93 Show tag refs found in `$GIT_DIR/refs/tags`.
95 --remotes::
96 Show tag refs found in `$GIT_DIR/refs/remotes`.
98 --show-prefix::
99 When the command is invoked from a subdirectory, show the
100 path of the current directory relative to the top-level
101 directory.
103 --show-cdup::
104 When the command is invoked from a subdirectory, show the
105 path of the top-level directory relative to the current
106 directory (typically a sequence of "../", or an empty string).
108 --git-dir::
109 Show `$GIT_DIR` if defined else show the path to the .git directory.
111 --is-inside-git-dir::
112 When the current working directory is below the repository
113 directory print "true", otherwise "false".
115 --is-inside-work-tree::
116 When the current working directory is inside the work tree of the
117 repository print "true", otherwise "false".
119 --is-bare-repository::
120 When the repository is bare print "true", otherwise "false".
122 --short, --short=number::
123 Instead of outputting the full SHA1 values of object names try to
124 abbreviate them to a shorter unique name. When no length is specified
125 7 is used. The minimum length is 4.
127 --since=datestring, --after=datestring::
128 Parses the date string, and outputs corresponding
129 --max-age= parameter for git-rev-list command.
131 --until=datestring, --before=datestring::
132 Parses the date string, and outputs corresponding
133 --min-age= parameter for git-rev-list command.
135 <args>...::
136 Flags and parameters to be parsed.
139 SPECIFYING REVISIONS
140 --------------------
142 A revision parameter typically, but not necessarily, names a
143 commit object. They use what is called an 'extended SHA1'
144 syntax. Here are various ways to spell object names. The
145 ones listed near the end of this list are to name trees and
146 blobs contained in a commit.
148 * The full SHA1 object name (40-byte hexadecimal string), or
149 a substring of such that is unique within the repository.
150 E.g. dae86e1950b1277e545cee180551750029cfe735 and dae86e both
151 name the same commit object if there are no other object in
152 your repository whose object name starts with dae86e.
154 * An output from `git-describe`; i.e. a closest tag, followed by a
155 dash, a `g`, and an abbreviated object name.
157 * A symbolic ref name. E.g. 'master' typically means the commit
158 object referenced by $GIT_DIR/refs/heads/master. If you
159 happen to have both heads/master and tags/master, you can
160 explicitly say 'heads/master' to tell git which one you mean.
161 When ambiguous, a `<name>` is disambiguated by taking the
162 first match in the following rules:
164 . if `$GIT_DIR/<name>` exists, that is what you mean (this is usually
165 useful only for `HEAD`, `FETCH_HEAD` and `MERGE_HEAD`);
167 . otherwise, `$GIT_DIR/refs/<name>` if exists;
169 . otherwise, `$GIT_DIR/refs/tags/<name>` if exists;
171 . otherwise, `$GIT_DIR/refs/heads/<name>` if exists;
173 . otherwise, `$GIT_DIR/refs/remotes/<name>` if exists;
175 . otherwise, `$GIT_DIR/refs/remotes/<name>/HEAD` if exists.
177 * A ref followed by the suffix '@' with a date specification
178 enclosed in a brace
179 pair (e.g. '\{yesterday\}', '\{1 month 2 weeks 3 days 1 hour 1
180 second ago\}' or '\{1979-02-26 18:30:00\}') to specify the value
181 of the ref at a prior point in time. This suffix may only be
182 used immediately following a ref name and the ref must have an
183 existing log ($GIT_DIR/logs/<ref>).
185 * A ref followed by the suffix '@' with an ordinal specification
186 enclosed in a brace pair (e.g. '\{1\}', '\{15\}') to specify
187 the n-th prior value of that ref. For example 'master@\{1\}'
188 is the immediate prior value of 'master' while 'master@\{5\}'
189 is the 5th prior value of 'master'. This suffix may only be used
190 immediately following a ref name and the ref must have an existing
191 log ($GIT_DIR/logs/<ref>).
193 * You can use the '@' construct with an empty ref part to get at a
194 reflog of the current branch. For example, if you are on the
195 branch 'blabla', then '@\{1\}' means the same as 'blabla@\{1\}'.
197 * A suffix '{caret}' to a revision parameter means the first parent of
198 that commit object. '{caret}<n>' means the <n>th parent (i.e.
199 'rev{caret}'
200 is equivalent to 'rev{caret}1'). As a special rule,
201 'rev{caret}0' means the commit itself and is used when 'rev' is the
202 object name of a tag object that refers to a commit object.
204 * A suffix '{tilde}<n>' to a revision parameter means the commit
205 object that is the <n>th generation grand-parent of the named
206 commit object, following only the first parent. I.e. rev~3 is
207 equivalent to rev{caret}{caret}{caret} which is equivalent to
208 rev{caret}1{caret}1{caret}1. See below for a illustration of
209 the usage of this form.
211 * A suffix '{caret}' followed by an object type name enclosed in
212 brace pair (e.g. `v0.99.8{caret}\{commit\}`) means the object
213 could be a tag, and dereference the tag recursively until an
214 object of that type is found or the object cannot be
215 dereferenced anymore (in which case, barf). `rev{caret}0`
216 introduced earlier is a short-hand for `rev{caret}\{commit\}`.
218 * A suffix '{caret}' followed by an empty brace pair
219 (e.g. `v0.99.8{caret}\{\}`) means the object could be a tag,
220 and dereference the tag recursively until a non-tag object is
221 found.
223 * A colon, followed by a slash, followed by a text: this names
224 a commit whose commit message starts with the specified text.
225 This name returns the youngest matching commit which is
226 reachable from any ref. If the commit message starts with a
227 '!', you have to repeat that; the special sequence ':/!',
228 followed by something else than '!' is reserved for now.
230 * A suffix ':' followed by a path; this names the blob or tree
231 at the given path in the tree-ish object named by the part
232 before the colon.
234 * A colon, optionally followed by a stage number (0 to 3) and a
235 colon, followed by a path; this names a blob object in the
236 index at the given path. Missing stage number (and the colon
237 that follows it) names a stage 0 entry. During a merge, stage
238 1 is the common ancestor, stage 2 is the target branch's version
239 (typically the current branch), and stage 3 is the version from
240 the branch being merged.
242 Here is an illustration, by Jon Loeliger. Both commit nodes B
243 and C are parents of commit node A. Parent commits are ordered
244 left-to-right.
246 ........................................
247 G H I J
248 \ / \ /
249 D E F
250 \ | / \
251 \ | / |
252 \|/ |
253 B C
254 \ /
255 \ /
256 A
257 ........................................
259 A = = A^0
260 B = A^ = A^1 = A~1
261 C = A^2 = A^2
262 D = A^^ = A^1^1 = A~2
263 E = B^2 = A^^2
264 F = B^3 = A^^3
265 G = A^^^ = A^1^1^1 = A~3
266 H = D^2 = B^^2 = A^^^2 = A~2^2
267 I = F^ = B^3^ = A^^3^
268 J = F^2 = B^3^2 = A^^3^2
271 SPECIFYING RANGES
272 -----------------
274 History traversing commands such as `git-log` operate on a set
275 of commits, not just a single commit. To these commands,
276 specifying a single revision with the notation described in the
277 previous section means the set of commits reachable from that
278 commit, following the commit ancestry chain.
280 To exclude commits reachable from a commit, a prefix `{caret}`
281 notation is used. E.g. "`{caret}r1 r2`" means commits reachable
282 from `r2` but exclude the ones reachable from `r1`.
284 This set operation appears so often that there is a shorthand
285 for it. "`r1..r2`" is equivalent to "`{caret}r1 r2`". It is
286 the difference of two sets (subtract the set of commits
287 reachable from `r1` from the set of commits reachable from
288 `r2`).
290 A similar notation "`r1\...r2`" is called symmetric difference
291 of `r1` and `r2` and is defined as
292 "`r1 r2 --not $(git-merge-base --all r1 r2)`".
293 It is the set of commits that are reachable from either one of
294 `r1` or `r2` but not from both.
296 Two other shorthands for naming a set that is formed by a commit
297 and its parent commits exists. `r1{caret}@` notation means all
298 parents of `r1`. `r1{caret}!` includes commit `r1` but excludes
299 its all parents.
301 Here are a handful of examples:
303 D G H D
304 D F G H I J D F
305 ^G D H D
306 ^D B E I J F B
307 B...C G H D E B C
308 ^D B C E I J F B C
309 C^@ I J F
310 F^! D G H D F
312 PARSEOPT
313 --------
315 In `--parseopt` mode, `git-rev-parse` helps massaging options to bring to shell
316 scripts the same facilities C builtins have. It works as an option normalizer
317 (e.g. splits single switches aggregate values), a bit like `getopt(1)` does.
319 It takes on the standard input the specification of the options to parse and
320 understand, and echoes on the standard output a line suitable for `sh(1)` `eval`
321 to replace the arguments with normalized ones. In case of error, it outputs
322 usage on the standard error stream, and exits with code 129.
324 Input Format
325 ~~~~~~~~~~~~
327 `git-rev-parse --parseopt` input format is fully text based. It has two parts,
328 separated by a line that contains only `--`. The lines before the separator
329 (should be more than one) are used for the usage.
330 The lines after the separator describe the options.
332 Each line of options has this format:
334 ------------
335 <opt_spec><flags>* SP+ help LF
336 ------------
338 `<opt_spec>`::
339 its format is the short option character, then the long option name
340 separated by a comma. Both parts are not required, though at least one
341 is necessary. `h,help`, `dry-run` and `f` are all three correct
342 `<opt_spec>`.
344 `<flags>`::
345 `<flags>` are of `*`, `=`, `?` or `!`.
346 * Use `=` if the option takes an argument.
348 * Use `?` to mean that the option is optional (though its use is discouraged).
350 * Use `*` to mean that this option should not be listed in the usage
351 generated for the `-h` argument. It's shown for `--help-all` as
352 documented in linkgit:gitcli[7].
354 * Use `!` to not make the corresponding negated long option available.
356 The remainder of the line, after stripping the spaces, is used
357 as the help associated to the option.
359 Blank lines are ignored, and lines that don't match this specification are used
360 as option group headers (start the line with a space to create such
361 lines on purpose).
363 Example
364 ~~~~~~~
366 ------------
367 OPTS_SPEC="\
368 some-command [options] <args>...
370 some-command does foo and bar!
371 --
372 h,help show the help
374 foo some nifty option --foo
375 bar= some cool option --bar with an argument
377 An option group Header
378 C? option C with an optional argument"
380 eval `echo "$OPTS_SPEC" | git-rev-parse --parseopt -- "$@" || echo exit $?`
381 ------------
383 EXAMPLES
384 --------
386 * Print the object name of the current commit:
387 +
388 ------------
389 $ git rev-parse --verify HEAD
390 ------------
392 * Print the commit object name from the revision in the $REV shell variable:
393 +
394 ------------
395 $ git rev-parse --verify $REV
396 ------------
397 +
398 This will error out if $REV is empty or not a valid revision.
400 * Same as above:
401 +
402 ------------
403 $ git rev-parse --default master --verify $REV
404 ------------
405 +
406 but if $REV is empty, the commit object name from master will be printed.
409 Author
410 ------
411 Written by Linus Torvalds <torvalds@osdl.org> .
412 Junio C Hamano <junkio@cox.net> and Pierre Habouzit <madcoder@debian.org>
414 Documentation
415 --------------
416 Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
418 GIT
419 ---
420 Part of the linkgit:git[7] suite