Documentation: fix missing text for rev-parse --verify
[git.git] / Documentation / git-rev-parse.txt
1 git-rev-parse(1)
2 ================
5 ----
6 git-rev-parse - Pick out and massage parameters
10 --------
11 [verse]
12 'git rev-parse' [ --option ] <args>...
15 -----------
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.
26 -------
28 Operation Modes
29 ~~~~~~~~~~~~~~~
31 Each of these options must appear first on the command line.
33 --parseopt::
34         Use 'git rev-parse' in option parsing mode (see PARSEOPT section below).
36 --sq-quote::
37         Use 'git rev-parse' in shell quoting mode (see SQ-QUOTE
38         section below). In contrast to the `--sq` option below, this
39         mode does only quoting. Nothing else is done to command input.
41 Options for --parseopt
42 ~~~~~~~~~~~~~~~~~~~~~~
44 --keep-dashdash::
45         Only meaningful in `--parseopt` mode. Tells the option parser to echo
46         out the first `--` met instead of skipping it.
48 --stop-at-non-option::
49         Only meaningful in `--parseopt` mode.  Lets the option parser stop at
50         the first non-option argument.  This can be used to parse sub-commands
51         that take options themselves.
53 Options for Filtering
54 ~~~~~~~~~~~~~~~~~~~~~
56 --revs-only::
57         Do not output flags and parameters not meant for
58         'git rev-list' command.
60 --no-revs::
61         Do not output flags and parameters meant for
62         'git rev-list' command.
64 --flags::
65         Do not output non-flag parameters.
67 --no-flags::
68         Do not output flag parameters.
70 Options for Output
71 ~~~~~~~~~~~~~~~~~~
73 --default <arg>::
74         If there is no parameter given by the user, use `<arg>`
75         instead.
77 --prefix <arg>::
78         Behave as if 'git rev-parse' was invoked from the `<arg>`
79         subdirectory of the working tree.  Any relative filenames are
80         resolved as if they are prefixed by `<arg>` and will be printed
81         in that form.
83 This can be used to convert arguments to a command run in a subdirectory
84 so that they can still be used after moving to the top-level of the
85 repository.  For example:
87 ----
88 prefix=$(git rev-parse --show-prefix)
89 cd "$(git rev-parse --show-toplevel)"
90 eval "set -- $(git rev-parse --sq --prefix "$prefix" "$@")"
91 ----
93 --verify::
94         Verify that exactly one parameter is provided, and that it
95         can be turned into a raw 20-byte SHA-1 that can be used to
96         access the object database. If so, emit it to the standard
97         output; otherwise, error out.
99 If you want to make sure that the output actually names an object in
100 your object database and/or can be used as a specific type of object
101 you require, you can add "\^{type}" peeling operator to the parameter.
102 For example, `git rev-parse "$VAR^{commit}"` will make sure `$VAR`
103 names an existing object that is a commit-ish (i.e. a commit, or an
104 annotated tag that points at a commit).  To make sure that `$VAR`
105 names an existing object of any type, `git rev-parse "$VAR^{object}"`
106 can be used.
108 -q::
109 --quiet::
110         Only meaningful in `--verify` mode. Do not output an error
111         message if the first argument is not a valid object name;
112         instead exit with non-zero status silently.
114 --sq::
115         Usually the output is made one line per flag and
116         parameter.  This option makes output a single line,
117         properly quoted for consumption by shell.  Useful when
118         you expect your parameter to contain whitespaces and
119         newlines (e.g. when using pickaxe `-S` with
120         'git diff-{asterisk}'). In contrast to the `--sq-quote` option,
121         the command input is still interpreted as usual.
123 --not::
124         When showing object names, prefix them with '{caret}' and
125         strip '{caret}' prefix from the object names that already have
126         one.
128 --abbrev-ref[=(strict|loose)]::
129         A non-ambiguous short name of the objects name.
130         The option core.warnAmbiguousRefs is used to select the strict
131         abbreviation mode.
133 --short::
134 --short=number::
135         Instead of outputting the full SHA-1 values of object names try to
136         abbreviate them to a shorter unique name. When no length is specified
137         7 is used. The minimum length is 4.
139 --symbolic::
140         Usually the object names are output in SHA-1 form (with
141         possible '{caret}' prefix); this option makes them output in a
142         form as close to the original input as possible.
144 --symbolic-full-name::
145         This is similar to \--symbolic, but it omits input that
146         are not refs (i.e. branch or tag names; or more
147         explicitly disambiguating "heads/master" form, when you
148         want to name the "master" branch when there is an
149         unfortunately named tag "master"), and show them as full
150         refnames (e.g. "refs/heads/master").
152 Options for Objects
153 ~~~~~~~~~~~~~~~~~~~
155 --all::
156         Show all refs found in `refs/`.
158 --branches[=pattern]::
159 --tags[=pattern]::
160 --remotes[=pattern]::
161         Show all branches, tags, or remote-tracking branches,
162         respectively (i.e., refs found in `refs/heads`,
163         `refs/tags`, or `refs/remotes`, respectively).
165 If a `pattern` is given, only refs matching the given shell glob are
166 shown.  If the pattern does not contain a globbing character (`?`,
167 `*`, or `[`), it is turned into a prefix match by appending `/*`.
169 --glob=pattern::
170         Show all refs matching the shell glob pattern `pattern`. If
171         the pattern does not start with `refs/`, this is automatically
172         prepended.  If the pattern does not contain a globbing
173         character (`?`, `*`, or `[`), it is turned into a prefix
174         match by appending `/*`.
176 --disambiguate=<prefix>::
177         Show every object whose name begins with the given prefix.
178         The <prefix> must be at least 4 hexadecimal digits long to
179         avoid listing each and every object in the repository by
180         mistake.
182 Options for Files
183 ~~~~~~~~~~~~~~~~~
185 --local-env-vars::
186         List the GIT_* environment variables that are local to the
187         repository (e.g. GIT_DIR or GIT_WORK_TREE, but not GIT_EDITOR).
188         Only the names of the variables are listed, not their value,
189         even if they are set.
191 --git-dir::
192         Show `$GIT_DIR` if defined. Otherwise show the path to
193         the .git directory. The path shown, when relative, is
194         relative to the current working directory.
196 If `$GIT_DIR` is not defined and the current directory
197 is not detected to lie in a Git repository or work tree
198 print a message to stderr and exit with nonzero status.
200 --is-inside-git-dir::
201         When the current working directory is below the repository
202         directory print "true", otherwise "false".
204 --is-inside-work-tree::
205         When the current working directory is inside the work tree of the
206         repository print "true", otherwise "false".
208 --is-bare-repository::
209         When the repository is bare print "true", otherwise "false".
211 --resolve-git-dir <path>::
212         Check if <path> is a valid repository or a gitfile that
213         points at a valid repository, and print the location of the
214         repository.  If <path> is a gitfile then the resolved path
215         to the real repository is printed.
217 --show-cdup::
218         When the command is invoked from a subdirectory, show the
219         path of the top-level directory relative to the current
220         directory (typically a sequence of "../", or an empty string).
222 --show-prefix::
223         When the command is invoked from a subdirectory, show the
224         path of the current directory relative to the top-level
225         directory.
227 --show-toplevel::
228         Show the absolute path of the top-level directory.
230 Other Options
231 ~~~~~~~~~~~~~
233 --since=datestring::
234 --after=datestring::
235         Parse the date string, and output the corresponding
236         --max-age= parameter for 'git rev-list'.
238 --until=datestring::
239 --before=datestring::
240         Parse the date string, and output the corresponding
241         --min-age= parameter for 'git rev-list'.
243 <args>...::
244         Flags and parameters to be parsed.
247 include::revisions.txt[]
250 --------
252 In `--parseopt` mode, 'git rev-parse' helps massaging options to bring to shell
253 scripts the same facilities C builtins have. It works as an option normalizer
254 (e.g. splits single switches aggregate values), a bit like `getopt(1)` does.
256 It takes on the standard input the specification of the options to parse and
257 understand, and echoes on the standard output a string suitable for `sh(1)` `eval`
258 to replace the arguments with normalized ones.  In case of error, it outputs
259 usage on the standard error stream, and exits with code 129.
261 Note: Make sure you quote the result when passing it to `eval`.  See
262 below for an example.
264 Input Format
265 ~~~~~~~~~~~~
267 'git rev-parse --parseopt' input format is fully text based. It has two parts,
268 separated by a line that contains only `--`. The lines before the separator
269 (should be more than one) are used for the usage.
270 The lines after the separator describe the options.
272 Each line of options has this format:
274 ------------
275 <opt_spec><flags>* SP+ help LF
276 ------------
278 `<opt_spec>`::
279         its format is the short option character, then the long option name
280         separated by a comma. Both parts are not required, though at least one
281         is necessary. `h,help`, `dry-run` and `f` are all three correct
282         `<opt_spec>`.
284 `<flags>`::
285         `<flags>` are of `*`, `=`, `?` or `!`.
286         * Use `=` if the option takes an argument.
288         * Use `?` to mean that the option is optional (though its use is discouraged).
290         * Use `*` to mean that this option should not be listed in the usage
291           generated for the `-h` argument. It's shown for `--help-all` as
292           documented in linkgit:gitcli[7].
294         * Use `!` to not make the corresponding negated long option available.
296 The remainder of the line, after stripping the spaces, is used
297 as the help associated to the option.
299 Blank lines are ignored, and lines that don't match this specification are used
300 as option group headers (start the line with a space to create such
301 lines on purpose).
303 Example
304 ~~~~~~~
306 ------------
307 OPTS_SPEC="\
308 some-command [options] <args>...
310 some-command does foo and bar!
312 h,help    show the help
314 foo       some nifty option --foo
315 bar=      some cool option --bar with an argument
317   An option group Header
318 C?        option C with an optional argument"
320 eval "$(echo "$OPTS_SPEC" | git rev-parse --parseopt -- "$@" || echo exit $?)"
321 ------------
324 --------
326 In `--sq-quote` mode, 'git rev-parse' echoes on the standard output a
327 single line suitable for `sh(1)` `eval`. This line is made by
328 normalizing the arguments following `--sq-quote`. Nothing other than
329 quoting the arguments is done.
331 If you want command input to still be interpreted as usual by
332 'git rev-parse' before the output is shell quoted, see the `--sq`
333 option.
335 Example
336 ~~~~~~~
338 ------------
339 $ cat > <<\EOF
340 #!/bin/sh
341 args=$(git rev-parse --sq-quote "$@")   # quote user-supplied arguments
342 command="git frotz -n24 $args"          # and use it inside a handcrafted
343                                         # command line
344 eval "$command"
347 $ sh "a b'c"
348 ------------
351 --------
353 * Print the object name of the current commit:
355 ------------
356 $ git rev-parse --verify HEAD
357 ------------
359 * Print the commit object name from the revision in the $REV shell variable:
361 ------------
362 $ git rev-parse --verify $REV^{commit}
363 ------------
365 This will error out if $REV is empty or not a valid revision.
367 * Similar to above:
369 ------------
370 $ git rev-parse --default master --verify $REV
371 ------------
373 but if $REV is empty, the commit object name from master will be printed.
377 Part of the linkgit:git[1] suite