remote-bzr: recover from failed clones
[alt-git.git] / Documentation / git-rev-parse.txt
blob947d62fd25e4b326af44a6f6933e98d9cc3e7153
1 git-rev-parse(1)
2 ================
4 NAME
5 ----
6 git-rev-parse - Pick out and massage parameters
9 SYNOPSIS
10 --------
11 [verse]
12 'git rev-parse' [ --option ] <args>...
14 DESCRIPTION
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.
25 OPTIONS
26 -------
27 --parseopt::
28         Use 'git rev-parse' in option parsing mode (see PARSEOPT section below).
30 --keep-dashdash::
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.
39 --sq-quote::
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.
44 --revs-only::
45         Do not output flags and parameters not meant for
46         'git rev-list' command.
48 --no-revs::
49         Do not output flags and parameters meant for
50         'git rev-list' command.
52 --flags::
53         Do not output non-flag parameters.
55 --no-flags::
56         Do not output flag parameters.
58 --default <arg>::
59         If there is no parameter given by the user, use `<arg>`
60         instead.
62 --verify::
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}"`
75 can be used.
77 -q::
78 --quiet::
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.
83 --sq::
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.
92 --not::
93         When showing object names, prefix them with '{caret}' and
94         strip '{caret}' prefix from the object names that already have
95         one.
97 --symbolic::
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
113         abbreviation mode.
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
119         mistake.
121 --all::
122         Show all refs found in `refs/`.
124 --branches[=pattern]::
125 --tags[=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 `/*`.
135 --glob=pattern::
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 `/*`.
142 --show-toplevel::
143         Show the absolute path of the top-level directory.
145 --show-prefix::
146         When the command is invoked from a subdirectory, show the
147         path of the current directory relative to the top-level
148         directory.
150 --show-cdup::
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).
155 --git-dir::
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".
175 --local-env-vars::
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.
181 --short::
182 --short=number::
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.
187 --since=datestring::
188 --after=datestring::
189         Parse the date string, and output the corresponding
190         --max-age= parameter for 'git rev-list'.
192 --until=datestring::
193 --before=datestring::
194         Parse the date string, and output the corresponding
195         --min-age= parameter for 'git rev-list'.
197 <args>...::
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[]
209 PARSEOPT
210 --------
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.
224 Input Format
225 ~~~~~~~~~~~~
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:
234 ------------
235 <opt_spec><flags>* SP+ help LF
236 ------------
238 `<opt_spec>`::
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
242         `<opt_spec>`.
244 `<flags>`::
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
261 lines on purpose).
263 Example
264 ~~~~~~~
266 ------------
267 OPTS_SPEC="\
268 some-command [options] <args>...
270 some-command does foo and bar!
272 h,help    show the help
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 $?)"
281 ------------
283 SQ-QUOTE
284 --------
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`
293 option.
295 Example
296 ~~~~~~~
298 ------------
299 $ cat >your-git-script.sh <<\EOF
300 #!/bin/sh
301 args=$(git rev-parse --sq-quote "$@")   # quote user-supplied arguments
302 command="git frotz -n24 $args"          # and use it inside a handcrafted
303                                         # command line
304 eval "$command"
307 $ sh your-git-script.sh "a b'c"
308 ------------
310 EXAMPLES
311 --------
313 * Print the object name of the current commit:
315 ------------
316 $ git rev-parse --verify HEAD
317 ------------
319 * Print the commit object name from the revision in the $REV shell variable:
321 ------------
322 $ git rev-parse --verify $REV^{commit}
323 ------------
325 This will error out if $REV is empty or not a valid revision.
327 * Similar to above:
329 ------------
330 $ git rev-parse --default master --verify $REV
331 ------------
333 but if $REV is empty, the commit object name from master will be printed.
337 Part of the linkgit:git[1] suite