glossary: improve description of SHA-1 related topics
[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-------
21d47835 27--parseopt::
0b444cdb 28 Use 'git rev-parse' in option parsing mode (see PARSEOPT section below).
21d47835 29
2163e3f7 30--keep-dashdash::
21d47835
PH
31 Only meaningful in `--parseopt` mode. Tells the option parser to echo
32 out the first `--` met instead of skipping it.
33
6e0800ef
UKK
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
6a5d0b0a 37 that take options themselves.
6e0800ef 38
50325377 39--sq-quote::
0b444cdb 40 Use 'git rev-parse' in shell quoting mode (see SQ-QUOTE
50325377
CC
41 section below). In contrast to the `--sq` option below, this
42 mode does only quoting. Nothing else is done to command input.
43
5077fa9c
JH
44--revs-only::
45 Do not output flags and parameters not meant for
0b444cdb 46 'git rev-list' command.
5077fa9c
JH
47
48--no-revs::
49 Do not output flags and parameters meant for
0b444cdb 50 'git rev-list' command.
5077fa9c
JH
51
52--flags::
53 Do not output non-flag parameters.
54
55--no-flags::
56 Do not output flag parameters.
57
58--default <arg>::
59 If there is no parameter given by the user, use `<arg>`
60 instead.
61
62--verify::
63 The parameter given must be usable as a single, valid
64 object name. Otherwise barf and abort.
65
3240240f
SB
66-q::
67--quiet::
b1b35969
CC
68 Only meaningful in `--verify` mode. Do not output an error
69 message if the first argument is not a valid object name;
70 instead exit with non-zero status silently.
71
5077fa9c
JH
72--sq::
73 Usually the output is made one line per flag and
74 parameter. This option makes output a single line,
75 properly quoted for consumption by shell. Useful when
76 you expect your parameter to contain whitespaces and
77 newlines (e.g. when using pickaxe `-S` with
4cacbf67 78 'git diff-{asterisk}'). In contrast to the `--sq-quote` option,
50325377 79 the command input is still interpreted as usual.
5077fa9c
JH
80
81--not::
babfaba2
JF
82 When showing object names, prefix them with '{caret}' and
83 strip '{caret}' prefix from the object names that already have
5077fa9c
JH
84 one.
85
86--symbolic::
87 Usually the object names are output in SHA1 form (with
babfaba2 88 possible '{caret}' prefix); this option makes them output in a
5077fa9c
JH
89 form as close to the original input as possible.
90
a6d97d49
JH
91--symbolic-full-name::
92 This is similar to \--symbolic, but it omits input that
93 are not refs (i.e. branch or tag names; or more
94 explicitly disambiguating "heads/master" form, when you
95 want to name the "master" branch when there is an
96 unfortunately named tag "master"), and show them as full
97 refnames (e.g. "refs/heads/master").
5077fa9c 98
0adda936 99--abbrev-ref[=(strict|loose)]::
a45d3469
BW
100 A non-ambiguous short name of the objects name.
101 The option core.warnAmbiguousRefs is used to select the strict
102 abbreviation mode.
103
957d7406
JH
104--disambiguate=<prefix>::
105 Show every object whose name begins with the given prefix.
106 The <prefix> must be at least 4 hexadecimal digits long to
107 avoid listing each and every object in the repository by
108 mistake.
109
5077fa9c 110--all::
cc1b8d8b 111 Show all refs found in `refs/`.
5077fa9c 112
b09fe971 113--branches[=pattern]::
b09fe971 114--tags[=pattern]::
b09fe971 115--remotes[=pattern]::
e2b53e58 116 Show all branches, tags, or remote-tracking branches,
cc1b8d8b
JK
117 respectively (i.e., refs found in `refs/heads`,
118 `refs/tags`, or `refs/remotes`, respectively).
e2b53e58
TR
119+
120If a `pattern` is given, only refs matching the given shell glob are
121shown. If the pattern does not contain a globbing character (`?`,
6cf378f0 122`*`, or `[`), it is turned into a prefix match by appending `/*`.
e2b53e58
TR
123
124--glob=pattern::
125 Show all refs matching the shell glob pattern `pattern`. If
126 the pattern does not start with `refs/`, this is automatically
127 prepended. If the pattern does not contain a globbing
6cf378f0
JK
128 character (`?`, `*`, or `[`), it is turned into a prefix
129 match by appending `/*`.
a62be77f 130
7cceca5c
SD
131--show-toplevel::
132 Show the absolute path of the top-level directory.
133
5077fa9c 134--show-prefix::
5f94c730 135 When the command is invoked from a subdirectory, show the
5077fa9c
JH
136 path of the current directory relative to the top-level
137 directory.
7fc9d69f 138
5f94c730
JH
139--show-cdup::
140 When the command is invoked from a subdirectory, show the
141 path of the top-level directory relative to the current
142 directory (typically a sequence of "../", or an empty string).
143
735d80b3 144--git-dir::
80d868b0 145 Show `$GIT_DIR` if defined. Otherwise show the path to
d0740ce0
JS
146 the .git directory. The path shown, when relative, is
147 relative to the current working directory.
80d868b0
JN
148+
149If `$GIT_DIR` is not defined and the current directory
2de9b711 150is not detected to lie in a Git repository or work tree
80d868b0 151print a message to stderr and exit with nonzero status.
735d80b3 152
c9bf7be2 153--is-inside-git-dir::
4faac246
ML
154 When the current working directory is below the repository
155 directory print "true", otherwise "false".
156
892c41b9
ML
157--is-inside-work-tree::
158 When the current working directory is inside the work tree of the
159 repository print "true", otherwise "false".
160
493c774e
ML
161--is-bare-repository::
162 When the repository is bare print "true", otherwise "false".
c9bf7be2 163
94c8ccaa
GB
164--local-env-vars::
165 List the GIT_* environment variables that are local to the
166 repository (e.g. GIT_DIR or GIT_WORK_TREE, but not GIT_EDITOR).
167 Only the names of the variables are listed, not their value,
168 even if they are set.
169
3240240f
SB
170--short::
171--short=number::
735d80b3 172 Instead of outputting the full SHA1 values of object names try to
abda1ef5 173 abbreviate them to a shorter unique name. When no length is specified
735d80b3
JF
174 7 is used. The minimum length is 4.
175
3240240f
SB
176--since=datestring::
177--after=datestring::
483bc4f0 178 Parse the date string, and output the corresponding
0b444cdb 179 --max-age= parameter for 'git rev-list'.
a3114b34 180
3240240f
SB
181--until=datestring::
182--before=datestring::
483bc4f0 183 Parse the date string, and output the corresponding
0b444cdb 184 --min-age= parameter for 'git rev-list'.
a3114b34 185
7fc9d69f 186<args>...::
5077fa9c 187 Flags and parameters to be parsed.
7fc9d69f 188
abc06822 189--resolve-git-dir <path>::
0859c969
TA
190 Check if <path> is a valid repository or a gitfile that
191 points at a valid repository, and print the location of the
192 repository. If <path> is a gitfile then the resolved path
193 to the real repository is printed.
194
7fc9d69f 195
5a8f3117 196include::revisions.txt[]
be4c7014 197
21d47835
PH
198PARSEOPT
199--------
200
0b444cdb 201In `--parseopt` mode, 'git rev-parse' helps massaging options to bring to shell
21d47835
PH
202scripts the same facilities C builtins have. It works as an option normalizer
203(e.g. splits single switches aggregate values), a bit like `getopt(1)` does.
204
205It takes on the standard input the specification of the options to parse and
ac2e1e63 206understand, and echoes on the standard output a string suitable for `sh(1)` `eval`
21d47835
PH
207to replace the arguments with normalized ones. In case of error, it outputs
208usage on the standard error stream, and exits with code 129.
209
ac2e1e63
TR
210Note: Make sure you quote the result when passing it to `eval`. See
211below for an example.
212
21d47835
PH
213Input Format
214~~~~~~~~~~~~
215
0b444cdb 216'git rev-parse --parseopt' input format is fully text based. It has two parts,
21d47835
PH
217separated by a line that contains only `--`. The lines before the separator
218(should be more than one) are used for the usage.
219The lines after the separator describe the options.
220
221Each line of options has this format:
222
223------------
ff962a3f 224<opt_spec><flags>* SP+ help LF
21d47835
PH
225------------
226
227`<opt_spec>`::
228 its format is the short option character, then the long option name
229 separated by a comma. Both parts are not required, though at least one
230 is necessary. `h,help`, `dry-run` and `f` are all three correct
231 `<opt_spec>`.
232
ff962a3f
PH
233`<flags>`::
234 `<flags>` are of `*`, `=`, `?` or `!`.
235 * Use `=` if the option takes an argument.
236
237 * Use `?` to mean that the option is optional (though its use is discouraged).
238
239 * Use `*` to mean that this option should not be listed in the usage
240 generated for the `-h` argument. It's shown for `--help-all` as
a5af0e2c 241 documented in linkgit:gitcli[7].
ff962a3f
PH
242
243 * Use `!` to not make the corresponding negated long option available.
21d47835
PH
244
245The remainder of the line, after stripping the spaces, is used
246as the help associated to the option.
247
248Blank lines are ignored, and lines that don't match this specification are used
249as option group headers (start the line with a space to create such
250lines on purpose).
251
252Example
253~~~~~~~
254
255------------
256OPTS_SPEC="\
257some-command [options] <args>...
258
259some-command does foo and bar!
260--
261h,help show the help
262
263foo some nifty option --foo
264bar= some cool option --bar with an argument
265
266 An option group Header
267C? option C with an optional argument"
268
ac2e1e63 269eval "$(echo "$OPTS_SPEC" | git rev-parse --parseopt -- "$@" || echo exit $?)"
21d47835
PH
270------------
271
50325377
CC
272SQ-QUOTE
273--------
274
0b444cdb 275In `--sq-quote` mode, 'git rev-parse' echoes on the standard output a
50325377
CC
276single line suitable for `sh(1)` `eval`. This line is made by
277normalizing the arguments following `--sq-quote`. Nothing other than
278quoting the arguments is done.
279
280If you want command input to still be interpreted as usual by
0b444cdb 281'git rev-parse' before the output is shell quoted, see the `--sq`
50325377
CC
282option.
283
284Example
285~~~~~~~
286
287------------
288$ cat >your-git-script.sh <<\EOF
289#!/bin/sh
290args=$(git rev-parse --sq-quote "$@") # quote user-supplied arguments
291command="git frotz -n24 $args" # and use it inside a handcrafted
292 # command line
293eval "$command"
294EOF
295
296$ sh your-git-script.sh "a b'c"
297------------
298
824b5dc2
CC
299EXAMPLES
300--------
301
302* Print the object name of the current commit:
303+
304------------
305$ git rev-parse --verify HEAD
306------------
307
308* Print the commit object name from the revision in the $REV shell variable:
309+
310------------
311$ git rev-parse --verify $REV
312------------
313+
314This will error out if $REV is empty or not a valid revision.
315
316* Same as above:
317+
318------------
319$ git rev-parse --default master --verify $REV
320------------
321+
322but if $REV is empty, the commit object name from master will be printed.
323
7fc9d69f
JH
324GIT
325---
9e1f0a85 326Part of the linkgit:git[1] suite