6 git-rev-parse - Pick out and massage parameters
12 'git rev-parse' [ --option ] <args>...
17 Many Git porcelainish commands take mixture of flags
18 (i.e. parameters that begin with a dash '-') and parameters
19 meant for the underlying 'git rev-list' command they use internally
20 and flags and parameters for the other commands they use
21 downstream of 'git rev-list'. This command is used to
22 distinguish between them.
28 Use 'git rev-parse' in option parsing mode (see PARSEOPT section below).
31 Only meaningful in `--parseopt` mode. Tells the option parser to echo
32 out the first `--` met instead of skipping it.
34 --stop-at-non-option::
35 Only meaningful in `--parseopt` mode. Lets the option parser stop at
36 the first non-option argument. This can be used to parse sub-commands
37 that take options themselves.
40 Use 'git rev-parse' in shell quoting mode (see SQ-QUOTE
41 section below). In contrast to the `--sq` option below, this
42 mode does only quoting. Nothing else is done to command input.
45 Do not output flags and parameters not meant for
46 'git rev-list' command.
49 Do not output flags and parameters meant for
50 'git rev-list' command.
53 Do not output non-flag parameters.
56 Do not output flag parameters.
59 If there is no parameter given by the user, use `<arg>`
63 Verify that exactly one parameter is provided, and that it
64 can be turned into a raw 20-byte SHA-1 that can be used to
65 access the object database. If so, emit it to the standard
66 output; otherwise, error out.
68 If you want to make sure that the output actually names an object in
69 your object database and/or can be used as a specific type of object
70 you require, you can add "^{type}" peeling operator to the parmeter.
71 For example, `git rev-parse "$VAR^{commit}"` will make sure `$VAR`
72 names an existing object that is a commit-ish (i.e. a commit, or an
73 annotated tag that points at a commit). To make sure that `$VAR`
74 names an existing object of any type, `git rev-parse "$VAR^{object}"`
79 Only meaningful in `--verify` mode. Do not output an error
80 message if the first argument is not a valid object name;
81 instead exit with non-zero status silently.
84 Usually the output is made one line per flag and
85 parameter. This option makes output a single line,
86 properly quoted for consumption by shell. Useful when
87 you expect your parameter to contain whitespaces and
88 newlines (e.g. when using pickaxe `-S` with
89 'git diff-{asterisk}'). In contrast to the `--sq-quote` option,
90 the command input is still interpreted as usual.
93 When showing object names, prefix them with '{caret}' and
94 strip '{caret}' prefix from the object names that already have
98 Usually the object names are output in SHA-1 form (with
99 possible '{caret}' prefix); this option makes them output in a
100 form as close to the original input as possible.
102 --symbolic-full-name::
103 This is similar to \--symbolic, but it omits input that
104 are not refs (i.e. branch or tag names; or more
105 explicitly disambiguating "heads/master" form, when you
106 want to name the "master" branch when there is an
107 unfortunately named tag "master"), and show them as full
108 refnames (e.g. "refs/heads/master").
110 --abbrev-ref[=(strict|loose)]::
111 A non-ambiguous short name of the objects name.
112 The option core.warnAmbiguousRefs is used to select the strict
115 --disambiguate=<prefix>::
116 Show every object whose name begins with the given prefix.
117 The <prefix> must be at least 4 hexadecimal digits long to
118 avoid listing each and every object in the repository by
122 Show all refs found in `refs/`.
124 --branches[=pattern]::
126 --remotes[=pattern]::
127 Show all branches, tags, or remote-tracking branches,
128 respectively (i.e., refs found in `refs/heads`,
129 `refs/tags`, or `refs/remotes`, respectively).
131 If a `pattern` is given, only refs matching the given shell glob are
132 shown. If the pattern does not contain a globbing character (`?`,
133 `*`, or `[`), it is turned into a prefix match by appending `/*`.
136 Show all refs matching the shell glob pattern `pattern`. If
137 the pattern does not start with `refs/`, this is automatically
138 prepended. If the pattern does not contain a globbing
139 character (`?`, `*`, or `[`), it is turned into a prefix
140 match by appending `/*`.
143 Show the absolute path of the top-level directory.
146 When the command is invoked from a subdirectory, show the
147 path of the current directory relative to the top-level
151 When the command is invoked from a subdirectory, show the
152 path of the top-level directory relative to the current
153 directory (typically a sequence of "../", or an empty string).
156 Show `$GIT_DIR` if defined. Otherwise show the path to
157 the .git directory. The path shown, when relative, is
158 relative to the current working directory.
160 If `$GIT_DIR` is not defined and the current directory
161 is not detected to lie in a Git repository or work tree
162 print a message to stderr and exit with nonzero status.
164 --is-inside-git-dir::
165 When the current working directory is below the repository
166 directory print "true", otherwise "false".
168 --is-inside-work-tree::
169 When the current working directory is inside the work tree of the
170 repository print "true", otherwise "false".
172 --is-bare-repository::
173 When the repository is bare print "true", otherwise "false".
176 List the GIT_* environment variables that are local to the
177 repository (e.g. GIT_DIR or GIT_WORK_TREE, but not GIT_EDITOR).
178 Only the names of the variables are listed, not their value,
179 even if they are set.
183 Instead of outputting the full SHA-1 values of object names try to
184 abbreviate them to a shorter unique name. When no length is specified
185 7 is used. The minimum length is 4.
189 Parse the date string, and output the corresponding
190 --max-age= parameter for 'git rev-list'.
193 --before=datestring::
194 Parse the date string, and output the corresponding
195 --min-age= parameter for 'git rev-list'.
198 Flags and parameters to be parsed.
200 --resolve-git-dir <path>::
201 Check if <path> is a valid repository or a gitfile that
202 points at a valid repository, and print the location of the
203 repository. If <path> is a gitfile then the resolved path
204 to the real repository is printed.
207 include::revisions.txt[]
212 In `--parseopt` mode, 'git rev-parse' helps massaging options to bring to shell
213 scripts the same facilities C builtins have. It works as an option normalizer
214 (e.g. splits single switches aggregate values), a bit like `getopt(1)` does.
216 It takes on the standard input the specification of the options to parse and
217 understand, and echoes on the standard output a string suitable for `sh(1)` `eval`
218 to replace the arguments with normalized ones. In case of error, it outputs
219 usage on the standard error stream, and exits with code 129.
221 Note: Make sure you quote the result when passing it to `eval`. See
222 below for an example.
227 'git rev-parse --parseopt' input format is fully text based. It has two parts,
228 separated by a line that contains only `--`. The lines before the separator
229 (should be more than one) are used for the usage.
230 The lines after the separator describe the options.
232 Each line of options has this format:
235 <opt_spec><flags>* SP+ help LF
239 its format is the short option character, then the long option name
240 separated by a comma. Both parts are not required, though at least one
241 is necessary. `h,help`, `dry-run` and `f` are all three correct
245 `<flags>` are of `*`, `=`, `?` or `!`.
246 * Use `=` if the option takes an argument.
248 * Use `?` to mean that the option is optional (though its use is discouraged).
250 * Use `*` to mean that this option should not be listed in the usage
251 generated for the `-h` argument. It's shown for `--help-all` as
252 documented in linkgit:gitcli[7].
254 * Use `!` to not make the corresponding negated long option available.
256 The remainder of the line, after stripping the spaces, is used
257 as the help associated to the option.
259 Blank lines are ignored, and lines that don't match this specification are used
260 as option group headers (start the line with a space to create such
268 some-command [options] <args>...
270 some-command does foo and bar!
274 foo some nifty option --foo
275 bar= some cool option --bar with an argument
277 An option group Header
278 C? option C with an optional argument"
280 eval "$(echo "$OPTS_SPEC" | git rev-parse --parseopt -- "$@" || echo exit $?)"
286 In `--sq-quote` mode, 'git rev-parse' echoes on the standard output a
287 single line suitable for `sh(1)` `eval`. This line is made by
288 normalizing the arguments following `--sq-quote`. Nothing other than
289 quoting the arguments is done.
291 If you want command input to still be interpreted as usual by
292 'git rev-parse' before the output is shell quoted, see the `--sq`
299 $ cat >your-git-script.sh <<\EOF
301 args=$(git rev-parse --sq-quote "$@") # quote user-supplied arguments
302 command="git frotz -n24 $args" # and use it inside a handcrafted
307 $ sh your-git-script.sh "a b'c"
313 * Print the object name of the current commit:
316 $ git rev-parse --verify HEAD
319 * Print the commit object name from the revision in the $REV shell variable:
322 $ git rev-parse --verify $REV^{commit}
325 This will error out if $REV is empty or not a valid revision.
330 $ git rev-parse --default master --verify $REV
333 but if $REV is empty, the commit object name from master will be printed.
337 Part of the linkgit:git[1] suite
projects / git / blob