Use the word 'stuck' instead of 'sticked'
[git/git.git] / Documentation / git-rev-parse.txt
CommitLineData
7fc9d69f
JH
1git-rev-parse(1)
2================
3
4NAME
5----
7bd7f280 6git-rev-parse - Pick out and massage parameters
7fc9d69f
JH
7
8
9SYNOPSIS
10--------
7791a1d9 11[verse]
b1889c36 12'git rev-parse' [ --option ] <args>...
7fc9d69f
JH
13
14DESCRIPTION
15-----------
5077fa9c 16
2de9b711 17Many Git porcelainish commands take mixture of flags
5077fa9c 18(i.e. parameters that begin with a dash '-') and parameters
0b444cdb 19meant for the underlying 'git rev-list' command they use internally
483bc4f0 20and flags and parameters for the other commands they use
0b444cdb 21downstream of 'git rev-list'. This command is used to
5077fa9c 22distinguish between them.
7fc9d69f
JH
23
24
25OPTIONS
26-------
49c63913
JK
27
28Operation Modes
29~~~~~~~~~~~~~~~
30
31Each of these options must appear first on the command line.
32
21d47835 33--parseopt::
0b444cdb 34 Use 'git rev-parse' in option parsing mode (see PARSEOPT section below).
21d47835 35
49c63913
JK
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.
40
41Options for --parseopt
42~~~~~~~~~~~~~~~~~~~~~~
43
2163e3f7 44--keep-dashdash::
21d47835
PH
45 Only meaningful in `--parseopt` mode. Tells the option parser to echo
46 out the first `--` met instead of skipping it.
47
6e0800ef
UKK
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
6a5d0b0a 51 that take options themselves.
6e0800ef 52
49c63913
JK
53Options for Filtering
54~~~~~~~~~~~~~~~~~~~~~
50325377 55
5077fa9c
JH
56--revs-only::
57 Do not output flags and parameters not meant for
0b444cdb 58 'git rev-list' command.
5077fa9c
JH
59
60--no-revs::
61 Do not output flags and parameters meant for
0b444cdb 62 'git rev-list' command.
5077fa9c
JH
63
64--flags::
65 Do not output non-flag parameters.
66
67--no-flags::
68 Do not output flag parameters.
69
49c63913
JK
70Options for Output
71~~~~~~~~~~~~~~~~~~
72
5077fa9c
JH
73--default <arg>::
74 If there is no parameter given by the user, use `<arg>`
75 instead.
76
12b9d327
JK
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.
82+
83This can be used to convert arguments to a command run in a subdirectory
84so that they can still be used after moving to the top-level of the
85repository. For example:
86+
87----
88prefix=$(git rev-parse --show-prefix)
89cd "$(git rev-parse --show-toplevel)"
90eval "set -- $(git rev-parse --sq --prefix "$prefix" "$@")"
91----
92
5077fa9c 93--verify::
2db60670
MH
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.
98+
99If you want to make sure that the output actually names an object in
100your object database and/or can be used as a specific type of object
17b83d71 101you require, you can add "^{type}" peeling operator to the parameter.
2db60670
MH
102For example, `git rev-parse "$VAR^{commit}"` will make sure `$VAR`
103names an existing object that is a commit-ish (i.e. a commit, or an
104annotated tag that points at a commit). To make sure that `$VAR`
105names an existing object of any type, `git rev-parse "$VAR^{object}"`
106can be used.
5077fa9c 107
3240240f
SB
108-q::
109--quiet::
b1b35969
CC
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.
113
5077fa9c
JH
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
4cacbf67 120 'git diff-{asterisk}'). In contrast to the `--sq-quote` option,
50325377 121 the command input is still interpreted as usual.
5077fa9c
JH
122
123--not::
babfaba2
JF
124 When showing object names, prefix them with '{caret}' and
125 strip '{caret}' prefix from the object names that already have
5077fa9c
JH
126 one.
127
49c63913
JK
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.
132
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.
138
5077fa9c 139--symbolic::
d5fa1f1a 140 Usually the object names are output in SHA-1 form (with
babfaba2 141 possible '{caret}' prefix); this option makes them output in a
5077fa9c
JH
142 form as close to the original input as possible.
143
a6d97d49
JH
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").
5077fa9c 151
49c63913
JK
152Options for Objects
153~~~~~~~~~~~~~~~~~~~
957d7406 154
5077fa9c 155--all::
cc1b8d8b 156 Show all refs found in `refs/`.
5077fa9c 157
b09fe971 158--branches[=pattern]::
b09fe971 159--tags[=pattern]::
b09fe971 160--remotes[=pattern]::
e2b53e58 161 Show all branches, tags, or remote-tracking branches,
cc1b8d8b
JK
162 respectively (i.e., refs found in `refs/heads`,
163 `refs/tags`, or `refs/remotes`, respectively).
e2b53e58
TR
164+
165If a `pattern` is given, only refs matching the given shell glob are
166shown. If the pattern does not contain a globbing character (`?`,
6cf378f0 167`*`, or `[`), it is turned into a prefix match by appending `/*`.
e2b53e58
TR
168
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
6cf378f0
JK
173 character (`?`, `*`, or `[`), it is turned into a prefix
174 match by appending `/*`.
a62be77f 175
49c63913
JK
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.
7cceca5c 181
49c63913
JK
182Options for Files
183~~~~~~~~~~~~~~~~~
7fc9d69f 184
49c63913
JK
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.
5f94c730 190
735d80b3 191--git-dir::
80d868b0 192 Show `$GIT_DIR` if defined. Otherwise show the path to
d0740ce0
JS
193 the .git directory. The path shown, when relative, is
194 relative to the current working directory.
80d868b0
JN
195+
196If `$GIT_DIR` is not defined and the current directory
2de9b711 197is not detected to lie in a Git repository or work tree
80d868b0 198print a message to stderr and exit with nonzero status.
735d80b3 199
c9bf7be2 200--is-inside-git-dir::
4faac246
ML
201 When the current working directory is below the repository
202 directory print "true", otherwise "false".
203
892c41b9
ML
204--is-inside-work-tree::
205 When the current working directory is inside the work tree of the
206 repository print "true", otherwise "false".
207
493c774e
ML
208--is-bare-repository::
209 When the repository is bare print "true", otherwise "false".
c9bf7be2 210
49c63913
JK
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.
94c8ccaa 216
49c63913
JK
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).
221
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.
226
227--show-toplevel::
228 Show the absolute path of the top-level directory.
229
230Other Options
231~~~~~~~~~~~~~
735d80b3 232
3240240f
SB
233--since=datestring::
234--after=datestring::
483bc4f0 235 Parse the date string, and output the corresponding
0b444cdb 236 --max-age= parameter for 'git rev-list'.
a3114b34 237
3240240f
SB
238--until=datestring::
239--before=datestring::
483bc4f0 240 Parse the date string, and output the corresponding
0b444cdb 241 --min-age= parameter for 'git rev-list'.
a3114b34 242
7fc9d69f 243<args>...::
5077fa9c 244 Flags and parameters to be parsed.
7fc9d69f
JH
245
246
5a8f3117 247include::revisions.txt[]
be4c7014 248
21d47835
PH
249PARSEOPT
250--------
251
0b444cdb 252In `--parseopt` mode, 'git rev-parse' helps massaging options to bring to shell
21d47835
PH
253scripts 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.
255
256It takes on the standard input the specification of the options to parse and
ac2e1e63 257understand, and echoes on the standard output a string suitable for `sh(1)` `eval`
21d47835
PH
258to replace the arguments with normalized ones. In case of error, it outputs
259usage on the standard error stream, and exits with code 129.
260
ac2e1e63
TR
261Note: Make sure you quote the result when passing it to `eval`. See
262below for an example.
263
21d47835
PH
264Input Format
265~~~~~~~~~~~~
266
0b444cdb 267'git rev-parse --parseopt' input format is fully text based. It has two parts,
21d47835
PH
268separated by a line that contains only `--`. The lines before the separator
269(should be more than one) are used for the usage.
270The lines after the separator describe the options.
271
272Each line of options has this format:
273
274------------
ff962a3f 275<opt_spec><flags>* SP+ help LF
21d47835
PH
276------------
277
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>`.
283
ff962a3f
PH
284`<flags>`::
285 `<flags>` are of `*`, `=`, `?` or `!`.
286 * Use `=` if the option takes an argument.
287
288 * Use `?` to mean that the option is optional (though its use is discouraged).
289
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
a5af0e2c 292 documented in linkgit:gitcli[7].
ff962a3f
PH
293
294 * Use `!` to not make the corresponding negated long option available.
21d47835
PH
295
296The remainder of the line, after stripping the spaces, is used
297as the help associated to the option.
298
299Blank lines are ignored, and lines that don't match this specification are used
300as option group headers (start the line with a space to create such
301lines on purpose).
302
303Example
304~~~~~~~
305
306------------
307OPTS_SPEC="\
308some-command [options] <args>...
309
310some-command does foo and bar!
311--
312h,help show the help
313
314foo some nifty option --foo
315bar= some cool option --bar with an argument
316
317 An option group Header
318C? option C with an optional argument"
319
ac2e1e63 320eval "$(echo "$OPTS_SPEC" | git rev-parse --parseopt -- "$@" || echo exit $?)"
21d47835
PH
321------------
322
50325377
CC
323SQ-QUOTE
324--------
325
0b444cdb 326In `--sq-quote` mode, 'git rev-parse' echoes on the standard output a
50325377
CC
327single line suitable for `sh(1)` `eval`. This line is made by
328normalizing the arguments following `--sq-quote`. Nothing other than
329quoting the arguments is done.
330
331If you want command input to still be interpreted as usual by
0b444cdb 332'git rev-parse' before the output is shell quoted, see the `--sq`
50325377
CC
333option.
334
335Example
336~~~~~~~
337
338------------
339$ cat >your-git-script.sh <<\EOF
340#!/bin/sh
341args=$(git rev-parse --sq-quote "$@") # quote user-supplied arguments
342command="git frotz -n24 $args" # and use it inside a handcrafted
343 # command line
344eval "$command"
345EOF
346
347$ sh your-git-script.sh "a b'c"
348------------
349
824b5dc2
CC
350EXAMPLES
351--------
352
353* Print the object name of the current commit:
354+
355------------
356$ git rev-parse --verify HEAD
357------------
358
359* Print the commit object name from the revision in the $REV shell variable:
360+
361------------
2db60670 362$ git rev-parse --verify $REV^{commit}
824b5dc2
CC
363------------
364+
365This will error out if $REV is empty or not a valid revision.
366
2db60670 367* Similar to above:
824b5dc2
CC
368+
369------------
370$ git rev-parse --default master --verify $REV
371------------
372+
373but if $REV is empty, the commit object name from master will be printed.
374
7fc9d69f
JH
375GIT
376---
9e1f0a85 377Part of the linkgit:git[1] suite