You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
318 lines
9.0 KiB
318 lines
9.0 KiB
git-rev-parse(1) |
|
================ |
|
|
|
NAME |
|
---- |
|
git-rev-parse - Pick out and massage parameters |
|
|
|
|
|
SYNOPSIS |
|
-------- |
|
'git rev-parse' [ --option ] <args>... |
|
|
|
DESCRIPTION |
|
----------- |
|
|
|
Many git porcelainish commands take mixture of flags |
|
(i.e. parameters that begin with a dash '-') and parameters |
|
meant for the underlying 'git rev-list' command they use internally |
|
and flags and parameters for the other commands they use |
|
downstream of 'git rev-list'. This command is used to |
|
distinguish between them. |
|
|
|
|
|
OPTIONS |
|
------- |
|
--parseopt:: |
|
Use 'git rev-parse' in option parsing mode (see PARSEOPT section below). |
|
|
|
--keep-dashdash:: |
|
Only meaningful in `--parseopt` mode. Tells the option parser to echo |
|
out the first `--` met instead of skipping it. |
|
|
|
--stop-at-non-option:: |
|
Only meaningful in `--parseopt` mode. Lets the option parser stop at |
|
the first non-option argument. This can be used to parse sub-commands |
|
that take options themselves. |
|
|
|
--sq-quote:: |
|
Use 'git rev-parse' in shell quoting mode (see SQ-QUOTE |
|
section below). In contrast to the `--sq` option below, this |
|
mode does only quoting. Nothing else is done to command input. |
|
|
|
--revs-only:: |
|
Do not output flags and parameters not meant for |
|
'git rev-list' command. |
|
|
|
--no-revs:: |
|
Do not output flags and parameters meant for |
|
'git rev-list' command. |
|
|
|
--flags:: |
|
Do not output non-flag parameters. |
|
|
|
--no-flags:: |
|
Do not output flag parameters. |
|
|
|
--default <arg>:: |
|
If there is no parameter given by the user, use `<arg>` |
|
instead. |
|
|
|
--verify:: |
|
The parameter given must be usable as a single, valid |
|
object name. Otherwise barf and abort. |
|
|
|
-q:: |
|
--quiet:: |
|
Only meaningful in `--verify` mode. Do not output an error |
|
message if the first argument is not a valid object name; |
|
instead exit with non-zero status silently. |
|
|
|
--sq:: |
|
Usually the output is made one line per flag and |
|
parameter. This option makes output a single line, |
|
properly quoted for consumption by shell. Useful when |
|
you expect your parameter to contain whitespaces and |
|
newlines (e.g. when using pickaxe `-S` with |
|
'git diff-{asterisk}'). In contrast to the `--sq-quote` option, |
|
the command input is still interpreted as usual. |
|
|
|
--not:: |
|
When showing object names, prefix them with '{caret}' and |
|
strip '{caret}' prefix from the object names that already have |
|
one. |
|
|
|
--symbolic:: |
|
Usually the object names are output in SHA1 form (with |
|
possible '{caret}' prefix); this option makes them output in a |
|
form as close to the original input as possible. |
|
|
|
--symbolic-full-name:: |
|
This is similar to \--symbolic, but it omits input that |
|
are not refs (i.e. branch or tag names; or more |
|
explicitly disambiguating "heads/master" form, when you |
|
want to name the "master" branch when there is an |
|
unfortunately named tag "master"), and show them as full |
|
refnames (e.g. "refs/heads/master"). |
|
|
|
--abbrev-ref[=(strict|loose)]:: |
|
A non-ambiguous short name of the objects name. |
|
The option core.warnAmbiguousRefs is used to select the strict |
|
abbreviation mode. |
|
|
|
--all:: |
|
Show all refs found in `refs/`. |
|
|
|
--branches[=pattern]:: |
|
--tags[=pattern]:: |
|
--remotes[=pattern]:: |
|
Show all branches, tags, or remote-tracking branches, |
|
respectively (i.e., refs found in `refs/heads`, |
|
`refs/tags`, or `refs/remotes`, respectively). |
|
+ |
|
If a `pattern` is given, only refs matching the given shell glob are |
|
shown. If the pattern does not contain a globbing character (`?`, |
|
`{asterisk}`, or `[`), it is turned into a prefix match by |
|
appending `/{asterisk}`. |
|
|
|
--glob=pattern:: |
|
Show all refs matching the shell glob pattern `pattern`. If |
|
the pattern does not start with `refs/`, this is automatically |
|
prepended. If the pattern does not contain a globbing |
|
character (`?`, `{asterisk}`, or `[`), it is turned into a prefix |
|
match by appending `/{asterisk}`. |
|
|
|
--show-toplevel:: |
|
Show the absolute path of the top-level directory. |
|
|
|
--show-prefix:: |
|
When the command is invoked from a subdirectory, show the |
|
path of the current directory relative to the top-level |
|
directory. |
|
|
|
--show-cdup:: |
|
When the command is invoked from a subdirectory, show the |
|
path of the top-level directory relative to the current |
|
directory (typically a sequence of "../", or an empty string). |
|
|
|
--git-dir:: |
|
Show `$GIT_DIR` if defined else show the path to the .git directory. |
|
|
|
--is-inside-git-dir:: |
|
When the current working directory is below the repository |
|
directory print "true", otherwise "false". |
|
|
|
--is-inside-work-tree:: |
|
When the current working directory is inside the work tree of the |
|
repository print "true", otherwise "false". |
|
|
|
--is-bare-repository:: |
|
When the repository is bare print "true", otherwise "false". |
|
|
|
--local-env-vars:: |
|
List the GIT_* environment variables that are local to the |
|
repository (e.g. GIT_DIR or GIT_WORK_TREE, but not GIT_EDITOR). |
|
Only the names of the variables are listed, not their value, |
|
even if they are set. |
|
|
|
--short:: |
|
--short=number:: |
|
Instead of outputting the full SHA1 values of object names try to |
|
abbreviate them to a shorter unique name. When no length is specified |
|
7 is used. The minimum length is 4. |
|
|
|
--since=datestring:: |
|
--after=datestring:: |
|
Parse the date string, and output the corresponding |
|
--max-age= parameter for 'git rev-list'. |
|
|
|
--until=datestring:: |
|
--before=datestring:: |
|
Parse the date string, and output the corresponding |
|
--min-age= parameter for 'git rev-list'. |
|
|
|
<args>...:: |
|
Flags and parameters to be parsed. |
|
|
|
|
|
include::revisions.txt[] |
|
|
|
PARSEOPT |
|
-------- |
|
|
|
In `--parseopt` mode, 'git rev-parse' helps massaging options to bring to shell |
|
scripts the same facilities C builtins have. It works as an option normalizer |
|
(e.g. splits single switches aggregate values), a bit like `getopt(1)` does. |
|
|
|
It takes on the standard input the specification of the options to parse and |
|
understand, and echoes on the standard output a string suitable for `sh(1)` `eval` |
|
to replace the arguments with normalized ones. In case of error, it outputs |
|
usage on the standard error stream, and exits with code 129. |
|
|
|
Note: Make sure you quote the result when passing it to `eval`. See |
|
below for an example. |
|
|
|
Input Format |
|
~~~~~~~~~~~~ |
|
|
|
'git rev-parse --parseopt' input format is fully text based. It has two parts, |
|
separated by a line that contains only `--`. The lines before the separator |
|
(should be more than one) are used for the usage. |
|
The lines after the separator describe the options. |
|
|
|
Each line of options has this format: |
|
|
|
------------ |
|
<opt_spec><flags>* SP+ help LF |
|
------------ |
|
|
|
`<opt_spec>`:: |
|
its format is the short option character, then the long option name |
|
separated by a comma. Both parts are not required, though at least one |
|
is necessary. `h,help`, `dry-run` and `f` are all three correct |
|
`<opt_spec>`. |
|
|
|
`<flags>`:: |
|
`<flags>` are of `*`, `=`, `?` or `!`. |
|
* Use `=` if the option takes an argument. |
|
|
|
* Use `?` to mean that the option is optional (though its use is discouraged). |
|
|
|
* Use `*` to mean that this option should not be listed in the usage |
|
generated for the `-h` argument. It's shown for `--help-all` as |
|
documented in linkgit:gitcli[7]. |
|
|
|
* Use `!` to not make the corresponding negated long option available. |
|
|
|
The remainder of the line, after stripping the spaces, is used |
|
as the help associated to the option. |
|
|
|
Blank lines are ignored, and lines that don't match this specification are used |
|
as option group headers (start the line with a space to create such |
|
lines on purpose). |
|
|
|
Example |
|
~~~~~~~ |
|
|
|
------------ |
|
OPTS_SPEC="\ |
|
some-command [options] <args>... |
|
|
|
some-command does foo and bar! |
|
-- |
|
h,help show the help |
|
|
|
foo some nifty option --foo |
|
bar= some cool option --bar with an argument |
|
|
|
An option group Header |
|
C? option C with an optional argument" |
|
|
|
eval "$(echo "$OPTS_SPEC" | git rev-parse --parseopt -- "$@" || echo exit $?)" |
|
------------ |
|
|
|
SQ-QUOTE |
|
-------- |
|
|
|
In `--sq-quote` mode, 'git rev-parse' echoes on the standard output a |
|
single line suitable for `sh(1)` `eval`. This line is made by |
|
normalizing the arguments following `--sq-quote`. Nothing other than |
|
quoting the arguments is done. |
|
|
|
If you want command input to still be interpreted as usual by |
|
'git rev-parse' before the output is shell quoted, see the `--sq` |
|
option. |
|
|
|
Example |
|
~~~~~~~ |
|
|
|
------------ |
|
$ cat >your-git-script.sh <<\EOF |
|
#!/bin/sh |
|
args=$(git rev-parse --sq-quote "$@") # quote user-supplied arguments |
|
command="git frotz -n24 $args" # and use it inside a handcrafted |
|
# command line |
|
eval "$command" |
|
EOF |
|
|
|
$ sh your-git-script.sh "a b'c" |
|
------------ |
|
|
|
EXAMPLES |
|
-------- |
|
|
|
* Print the object name of the current commit: |
|
+ |
|
------------ |
|
$ git rev-parse --verify HEAD |
|
------------ |
|
|
|
* Print the commit object name from the revision in the $REV shell variable: |
|
+ |
|
------------ |
|
$ git rev-parse --verify $REV |
|
------------ |
|
+ |
|
This will error out if $REV is empty or not a valid revision. |
|
|
|
* Same as above: |
|
+ |
|
------------ |
|
$ git rev-parse --default master --verify $REV |
|
------------ |
|
+ |
|
but if $REV is empty, the commit object name from master will be printed. |
|
|
|
|
|
Author |
|
------ |
|
Written by Linus Torvalds <torvalds@osdl.org> . |
|
Junio C Hamano <gitster@pobox.com> and Pierre Habouzit <madcoder@debian.org> |
|
|
|
Documentation |
|
-------------- |
|
Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. |
|
|
|
GIT |
|
--- |
|
Part of the linkgit:git[1] suite
|
|
|