6 git-rev-parse - Pick out and massage parameters
11 'git-rev-parse' [ --option ] <args>...
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.
27 Use `git-rev-parse` in option parsing mode (see PARSEOPT section below).
30 Only meaningful in `--parseopt` mode. Tells the option parser to echo
31 out the first `--` met instead of skipping it.
34 Do not output flags and parameters not meant for
35 `git-rev-list` command.
38 Do not output flags and parameters meant for
39 `git-rev-list` command.
42 Do not output non-flag parameters.
45 Do not output flag parameters.
48 If there is no parameter given by the user, use `<arg>`
52 The parameter given must be usable as a single, valid
53 object name. Otherwise barf and abort.
56 Usually the output is made one line per flag and
57 parameter. This option makes output a single line,
58 properly quoted for consumption by shell. Useful when
59 you expect your parameter to contain whitespaces and
60 newlines (e.g. when using pickaxe `-S` with
64 When showing object names, prefix them with '{caret}' and
65 strip '{caret}' prefix from the object names that already have
69 Usually the object names are output in SHA1 form (with
70 possible '{caret}' prefix); this option makes them output in a
71 form as close to the original input as possible.
75 Show all refs found in `$GIT_DIR/refs`.
78 Show branch refs found in `$GIT_DIR/refs/heads`.
81 Show tag refs found in `$GIT_DIR/refs/tags`.
84 Show tag refs found in `$GIT_DIR/refs/remotes`.
87 When the command is invoked from a subdirectory, show the
88 path of the current directory relative to the top-level
92 When the command is invoked from a subdirectory, show the
93 path of the top-level directory relative to the current
94 directory (typically a sequence of "../", or an empty string).
97 Show `$GIT_DIR` if defined else show the path to the .git directory.
100 When the current working directory is below the repository
101 directory print "true", otherwise "false".
103 --is-inside-work-tree::
104 When the current working directory is inside the work tree of the
105 repository print "true", otherwise "false".
107 --is-bare-repository::
108 When the repository is bare print "true", otherwise "false".
110 --short, --short=number::
111 Instead of outputting the full SHA1 values of object names try to
112 abbreviate them to a shorter unique name. When no length is specified
113 7 is used. The minimum length is 4.
115 --since=datestring, --after=datestring::
116 Parses the date string, and outputs corresponding
117 --max-age= parameter for git-rev-list command.
119 --until=datestring, --before=datestring::
120 Parses the date string, and outputs corresponding
121 --min-age= parameter for git-rev-list command.
124 Flags and parameters to be parsed.
130 A revision parameter typically, but not necessarily, names a
131 commit object. They use what is called an 'extended SHA1'
132 syntax. Here are various ways to spell object names. The
133 ones listed near the end of this list are to name trees and
134 blobs contained in a commit.
136 * The full SHA1 object name (40-byte hexadecimal string), or
137 a substring of such that is unique within the repository.
138 E.g. dae86e1950b1277e545cee180551750029cfe735 and dae86e both
139 name the same commit object if there are no other object in
140 your repository whose object name starts with dae86e.
142 * An output from `git-describe`; i.e. a closest tag, followed by a
143 dash, a `g`, and an abbreviated object name.
145 * A symbolic ref name. E.g. 'master' typically means the commit
146 object referenced by $GIT_DIR/refs/heads/master. If you
147 happen to have both heads/master and tags/master, you can
148 explicitly say 'heads/master' to tell git which one you mean.
149 When ambiguous, a `<name>` is disambiguated by taking the
150 first match in the following rules:
152 . if `$GIT_DIR/<name>` exists, that is what you mean (this is usually
153 useful only for `HEAD`, `FETCH_HEAD` and `MERGE_HEAD`);
155 . otherwise, `$GIT_DIR/refs/<name>` if exists;
157 . otherwise, `$GIT_DIR/refs/tags/<name>` if exists;
159 . otherwise, `$GIT_DIR/refs/heads/<name>` if exists;
161 . otherwise, `$GIT_DIR/refs/remotes/<name>` if exists;
163 . otherwise, `$GIT_DIR/refs/remotes/<name>/HEAD` if exists.
165 * A ref followed by the suffix '@' with a date specification
167 pair (e.g. '\{yesterday\}', '\{1 month 2 weeks 3 days 1 hour 1
168 second ago\}' or '\{1979-02-26 18:30:00\}') to specify the value
169 of the ref at a prior point in time. This suffix may only be
170 used immediately following a ref name and the ref must have an
171 existing log ($GIT_DIR/logs/<ref>).
173 * A ref followed by the suffix '@' with an ordinal specification
174 enclosed in a brace pair (e.g. '\{1\}', '\{15\}') to specify
175 the n-th prior value of that ref. For example 'master@\{1\}'
176 is the immediate prior value of 'master' while 'master@\{5\}'
177 is the 5th prior value of 'master'. This suffix may only be used
178 immediately following a ref name and the ref must have an existing
179 log ($GIT_DIR/logs/<ref>).
181 * You can use the '@' construct with an empty ref part to get at a
182 reflog of the current branch. For example, if you are on the
183 branch 'blabla', then '@\{1\}' means the same as 'blabla@\{1\}'.
185 * A suffix '{caret}' to a revision parameter means the first parent of
186 that commit object. '{caret}<n>' means the <n>th parent (i.e.
188 is equivalent to 'rev{caret}1'). As a special rule,
189 'rev{caret}0' means the commit itself and is used when 'rev' is the
190 object name of a tag object that refers to a commit object.
192 * A suffix '{tilde}<n>' to a revision parameter means the commit
193 object that is the <n>th generation grand-parent of the named
194 commit object, following only the first parent. I.e. rev~3 is
195 equivalent to rev{caret}{caret}{caret} which is equivalent to
196 rev{caret}1{caret}1{caret}1. See below for a illustration of
197 the usage of this form.
199 * A suffix '{caret}' followed by an object type name enclosed in
200 brace pair (e.g. `v0.99.8{caret}\{commit\}`) means the object
201 could be a tag, and dereference the tag recursively until an
202 object of that type is found or the object cannot be
203 dereferenced anymore (in which case, barf). `rev{caret}0`
204 introduced earlier is a short-hand for `rev{caret}\{commit\}`.
206 * A suffix '{caret}' followed by an empty brace pair
207 (e.g. `v0.99.8{caret}\{\}`) means the object could be a tag,
208 and dereference the tag recursively until a non-tag object is
211 * A colon, followed by a slash, followed by a text: this names
212 a commit whose commit message starts with the specified text.
213 This name returns the youngest matching commit which is
214 reachable from any ref. If the commit message starts with a
215 '!', you have to repeat that; the special sequence ':/!',
216 followed by something else than '!' is reserved for now.
218 * A suffix ':' followed by a path; this names the blob or tree
219 at the given path in the tree-ish object named by the part
222 * A colon, optionally followed by a stage number (0 to 3) and a
223 colon, followed by a path; this names a blob object in the
224 index at the given path. Missing stage number (and the colon
225 that follows it) names an stage 0 entry. During a merge, stage
226 1 is the common ancestor, stage 2 is the target branch's version
227 (typically the current branch), and stage 3 is the version from
228 the branch being merged.
230 Here is an illustration, by Jon Loeliger. Both node B and C are
231 a commit parents of commit node A. Parent commits are ordered
248 D = A^^ = A^1^1 = A~2
251 G = A^^^ = A^1^1^1 = A~3
252 H = D^2 = B^^2 = A^^^2 = A~2^2
253 I = F^ = B^3^ = A^^3^
254 J = F^2 = B^3^2 = A^^3^2
260 History traversing commands such as `git-log` operate on a set
261 of commits, not just a single commit. To these commands,
262 specifying a single revision with the notation described in the
263 previous section means the set of commits reachable from that
264 commit, following the commit ancestry chain.
266 To exclude commits reachable from a commit, a prefix `{caret}`
267 notation is used. E.g. "`{caret}r1 r2`" means commits reachable
268 from `r2` but exclude the ones reachable from `r1`.
270 This set operation appears so often that there is a shorthand
271 for it. "`r1..r2`" is equivalent to "`{caret}r1 r2`". It is
272 the difference of two sets (subtract the set of commits
273 reachable from `r1` from the set of commits reachable from
276 A similar notation "`r1\...r2`" is called symmetric difference
277 of `r1` and `r2` and is defined as
278 "`r1 r2 --not $(git-merge-base --all r1 r2)`".
279 It is the set of commits that are reachable from either one of
280 `r1` or `r2` but not from both.
282 Two other shorthands for naming a set that is formed by a commit
283 and its parent commits exists. `r1{caret}@` notation means all
284 parents of `r1`. `r1{caret}!` includes commit `r1` but excludes
287 Here are a handful examples:
301 In `--parseopt` mode, `git-rev-parse` helps massaging options to bring to shell
302 scripts the same facilities C builtins have. It works as an option normalizer
303 (e.g. splits single switches aggregate values), a bit like `getopt(1)` does.
305 It takes on the standard input the specification of the options to parse and
306 understand, and echoes on the standard output a line suitable for `sh(1)` `eval`
307 to replace the arguments with normalized ones. In case of error, it outputs
308 usage on the standard error stream, and exits with code 129.
313 `git-rev-parse --parseopt` input format is fully text based. It has two parts,
314 separated by a line that contains only `--`. The lines before the separator
315 (should be more than one) are used for the usage.
316 The lines after the separator describe the options.
318 Each line of options has this format:
321 <opt_spec><arg_spec>? SP+ help LF
325 its format is the short option character, then the long option name
326 separated by a comma. Both parts are not required, though at least one
327 is necessary. `h,help`, `dry-run` and `f` are all three correct
331 an `<arg_spec>` tells the option parser if the option has an argument
332 (`=`), an optional one (`?` though its use is discouraged) or none
333 (no `<arg_spec>` in that case).
335 The remainder of the line, after stripping the spaces, is used
336 as the help associated to the option.
338 Blank lines are ignored, and lines that don't match this specification are used
339 as option group headers (start the line with a space to create such
347 some-command [options] <args>...
349 some-command does foo and bar!
353 foo some nifty option --foo
354 bar= some cool option --bar with an argument
356 An option group Header
357 C? option C with an optional argument"
359 eval `echo "$OPTS_SPEC" | git-rev-parse --parseopt -- "$@" || echo exit $?`
365 Written by Linus Torvalds <torvalds@osdl.org> .
366 Junio C Hamano <junkio@cox.net> and Pierre Habouzit <madcoder@debian.org>
370 Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
374 Part of the gitlink:git[7] suite