| '\" t |
| .\" Title: git-rev-parse |
| .\" Author: [FIXME: author] [see http://docbook.sf.net/el/author] |
| .\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/> |
| .\" Date: 12/09/2018 |
| .\" Manual: Git Manual |
| .\" Source: Git 2.20.0 |
| .\" Language: English |
| .\" |
| .TH "GIT\-REV\-PARSE" "1" "12/09/2018" "Git 2\&.20\&.0" "Git Manual" |
| .\" ----------------------------------------------------------------- |
| .\" * Define some portability stuff |
| .\" ----------------------------------------------------------------- |
| .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| .\" http://bugs.debian.org/507673 |
| .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html |
| .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| .ie \n(.g .ds Aq \(aq |
| .el .ds Aq ' |
| .\" ----------------------------------------------------------------- |
| .\" * set default formatting |
| .\" ----------------------------------------------------------------- |
| .\" disable hyphenation |
| .nh |
| .\" disable justification (adjust text to left margin only) |
| .ad l |
| .\" ----------------------------------------------------------------- |
| .\" * MAIN CONTENT STARTS HERE * |
| .\" ----------------------------------------------------------------- |
| .SH "NAME" |
| git-rev-parse \- Pick out and massage parameters |
| .SH "SYNOPSIS" |
| .sp |
| .nf |
| \fIgit rev\-parse\fR [<options>] <args>\&... |
| .fi |
| .sp |
| .SH "DESCRIPTION" |
| .sp |
| Many Git porcelainish commands take mixture of flags (i\&.e\&. parameters that begin with a dash \fI\-\fR) and parameters meant for the underlying \fIgit rev\-list\fR command they use internally and flags and parameters for the other commands they use downstream of \fIgit rev\-list\fR\&. This command is used to distinguish between them\&. |
| .SH "OPTIONS" |
| .SS "Operation Modes" |
| .sp |
| Each of these options must appear first on the command line\&. |
| .PP |
| \-\-parseopt |
| .RS 4 |
| Use |
| \fIgit rev\-parse\fR |
| in option parsing mode (see PARSEOPT section below)\&. |
| .RE |
| .PP |
| \-\-sq\-quote |
| .RS 4 |
| Use |
| \fIgit rev\-parse\fR |
| in shell quoting mode (see SQ\-QUOTE section below)\&. In contrast to the |
| \fB\-\-sq\fR |
| option below, this mode does only quoting\&. Nothing else is done to command input\&. |
| .RE |
| .SS "Options for \-\-parseopt" |
| .PP |
| \-\-keep\-dashdash |
| .RS 4 |
| Only meaningful in |
| \fB\-\-parseopt\fR |
| mode\&. Tells the option parser to echo out the first |
| \fB\-\-\fR |
| met instead of skipping it\&. |
| .RE |
| .PP |
| \-\-stop\-at\-non\-option |
| .RS 4 |
| Only meaningful in |
| \fB\-\-parseopt\fR |
| mode\&. Lets the option parser stop at the first non\-option argument\&. This can be used to parse sub\-commands that take options themselves\&. |
| .RE |
| .PP |
| \-\-stuck\-long |
| .RS 4 |
| Only meaningful in |
| \fB\-\-parseopt\fR |
| mode\&. Output the options in their long form if available, and with their arguments stuck\&. |
| .RE |
| .SS "Options for Filtering" |
| .PP |
| \-\-revs\-only |
| .RS 4 |
| Do not output flags and parameters not meant for |
| \fIgit rev\-list\fR |
| command\&. |
| .RE |
| .PP |
| \-\-no\-revs |
| .RS 4 |
| Do not output flags and parameters meant for |
| \fIgit rev\-list\fR |
| command\&. |
| .RE |
| .PP |
| \-\-flags |
| .RS 4 |
| Do not output non\-flag parameters\&. |
| .RE |
| .PP |
| \-\-no\-flags |
| .RS 4 |
| Do not output flag parameters\&. |
| .RE |
| .SS "Options for Output" |
| .PP |
| \-\-default <arg> |
| .RS 4 |
| If there is no parameter given by the user, use |
| \fB<arg>\fR |
| instead\&. |
| .RE |
| .PP |
| \-\-prefix <arg> |
| .RS 4 |
| Behave as if |
| \fIgit rev\-parse\fR |
| was invoked from the |
| \fB<arg>\fR |
| subdirectory of the working tree\&. Any relative filenames are resolved as if they are prefixed by |
| \fB<arg>\fR |
| and will be printed in that form\&. |
| .sp |
| This can be used to convert arguments to a command run in a subdirectory so that they can still be used after moving to the top\-level of the repository\&. For example: |
| .sp |
| .if n \{\ |
| .RS 4 |
| .\} |
| .nf |
| prefix=$(git rev\-parse \-\-show\-prefix) |
| cd "$(git rev\-parse \-\-show\-toplevel)" |
| # rev\-parse provides the \-\- needed for \(aqset\(aq |
| eval "set $(git rev\-parse \-\-sq \-\-prefix "$prefix" \-\- "$@")" |
| .fi |
| .if n \{\ |
| .RE |
| .\} |
| .sp |
| .RE |
| .PP |
| \-\-verify |
| .RS 4 |
| Verify that exactly one parameter is provided, and that it can be turned into a raw 20\-byte SHA\-1 that can be used to access the object database\&. If so, emit it to the standard output; otherwise, error out\&. |
| .sp |
| If you want to make sure that the output actually names an object in your object database and/or can be used as a specific type of object you require, you can add the |
| \fB^{type}\fR |
| peeling operator to the parameter\&. For example, |
| \fBgit rev\-parse "$VAR^{commit}"\fR |
| will make sure |
| \fB$VAR\fR |
| names an existing object that is a commit\-ish (i\&.e\&. a commit, or an annotated tag that points at a commit)\&. To make sure that |
| \fB$VAR\fR |
| names an existing object of any type, |
| \fBgit rev\-parse "$VAR^{object}"\fR |
| can be used\&. |
| .RE |
| .PP |
| \-q, \-\-quiet |
| .RS 4 |
| Only meaningful in |
| \fB\-\-verify\fR |
| mode\&. Do not output an error message if the first argument is not a valid object name; instead exit with non\-zero status silently\&. SHA\-1s for valid object names are printed to stdout on success\&. |
| .RE |
| .PP |
| \-\-sq |
| .RS 4 |
| 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 |
| \fB\-S\fR |
| with |
| \fIgit diff\-*\fR)\&. In contrast to the |
| \fB\-\-sq\-quote\fR |
| option, the command input is still interpreted as usual\&. |
| .RE |
| .PP |
| \-\-short[=length] |
| .RS 4 |
| Same as |
| \fB\-\-verify\fR |
| but shortens the object name to a unique prefix with at least |
| \fBlength\fR |
| characters\&. The minimum length is 4, the default is the effective value of the |
| \fBcore\&.abbrev\fR |
| configuration variable (see |
| \fBgit-config\fR(1))\&. |
| .RE |
| .PP |
| \-\-not |
| .RS 4 |
| When showing object names, prefix them with |
| \fI^\fR |
| and strip |
| \fI^\fR |
| prefix from the object names that already have one\&. |
| .RE |
| .PP |
| \-\-abbrev\-ref[=(strict|loose)] |
| .RS 4 |
| A non\-ambiguous short name of the objects name\&. The option core\&.warnAmbiguousRefs is used to select the strict abbreviation mode\&. |
| .RE |
| .PP |
| \-\-symbolic |
| .RS 4 |
| Usually the object names are output in SHA\-1 form (with possible |
| \fI^\fR |
| prefix); this option makes them output in a form as close to the original input as possible\&. |
| .RE |
| .PP |
| \-\-symbolic\-full\-name |
| .RS 4 |
| 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")\&. |
| .RE |
| .SS "Options for Objects" |
| .PP |
| \-\-all |
| .RS 4 |
| Show all refs found in |
| \fBrefs/\fR\&. |
| .RE |
| .PP |
| \-\-branches[=pattern], \-\-tags[=pattern], \-\-remotes[=pattern] |
| .RS 4 |
| Show all branches, tags, or remote\-tracking branches, respectively (i\&.e\&., refs found in |
| \fBrefs/heads\fR, |
| \fBrefs/tags\fR, or |
| \fBrefs/remotes\fR, respectively)\&. |
| .sp |
| If a |
| \fBpattern\fR |
| is given, only refs matching the given shell glob are shown\&. If the pattern does not contain a globbing character (\fB?\fR, |
| \fB*\fR, or |
| \fB[\fR), it is turned into a prefix match by appending |
| \fB/*\fR\&. |
| .RE |
| .PP |
| \-\-glob=pattern |
| .RS 4 |
| Show all refs matching the shell glob pattern |
| \fBpattern\fR\&. If the pattern does not start with |
| \fBrefs/\fR, this is automatically prepended\&. If the pattern does not contain a globbing character (\fB?\fR, |
| \fB*\fR, or |
| \fB[\fR), it is turned into a prefix match by appending |
| \fB/*\fR\&. |
| .RE |
| .PP |
| \-\-exclude=<glob\-pattern> |
| .RS 4 |
| Do not include refs matching |
| \fI<glob\-pattern>\fR |
| that the next |
| \fB\-\-all\fR, |
| \fB\-\-branches\fR, |
| \fB\-\-tags\fR, |
| \fB\-\-remotes\fR, or |
| \fB\-\-glob\fR |
| would otherwise consider\&. Repetitions of this option accumulate exclusion patterns up to the next |
| \fB\-\-all\fR, |
| \fB\-\-branches\fR, |
| \fB\-\-tags\fR, |
| \fB\-\-remotes\fR, or |
| \fB\-\-glob\fR |
| option (other options or arguments do not clear accumulated patterns)\&. |
| .sp |
| The patterns given should not begin with |
| \fBrefs/heads\fR, |
| \fBrefs/tags\fR, or |
| \fBrefs/remotes\fR |
| when applied to |
| \fB\-\-branches\fR, |
| \fB\-\-tags\fR, or |
| \fB\-\-remotes\fR, respectively, and they must begin with |
| \fBrefs/\fR |
| when applied to |
| \fB\-\-glob\fR |
| or |
| \fB\-\-all\fR\&. If a trailing |
| \fI/*\fR |
| is intended, it must be given explicitly\&. |
| .RE |
| .PP |
| \-\-disambiguate=<prefix> |
| .RS 4 |
| Show every object whose name begins with the given prefix\&. The <prefix> must be at least 4 hexadecimal digits long to avoid listing each and every object in the repository by mistake\&. |
| .RE |
| .SS "Options for Files" |
| .PP |
| \-\-local\-env\-vars |
| .RS 4 |
| 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\&. |
| .RE |
| .PP |
| \-\-git\-dir |
| .RS 4 |
| Show |
| \fB$GIT_DIR\fR |
| if defined\&. Otherwise show the path to the \&.git directory\&. The path shown, when relative, is relative to the current working directory\&. |
| .sp |
| If |
| \fB$GIT_DIR\fR |
| is not defined and the current directory is not detected to lie in a Git repository or work tree print a message to stderr and exit with nonzero status\&. |
| .RE |
| .PP |
| \-\-absolute\-git\-dir |
| .RS 4 |
| Like |
| \fB\-\-git\-dir\fR, but its output is always the canonicalized absolute path\&. |
| .RE |
| .PP |
| \-\-git\-common\-dir |
| .RS 4 |
| Show |
| \fB$GIT_COMMON_DIR\fR |
| if defined, else |
| \fB$GIT_DIR\fR\&. |
| .RE |
| .PP |
| \-\-is\-inside\-git\-dir |
| .RS 4 |
| When the current working directory is below the repository directory print "true", otherwise "false"\&. |
| .RE |
| .PP |
| \-\-is\-inside\-work\-tree |
| .RS 4 |
| When the current working directory is inside the work tree of the repository print "true", otherwise "false"\&. |
| .RE |
| .PP |
| \-\-is\-bare\-repository |
| .RS 4 |
| When the repository is bare print "true", otherwise "false"\&. |
| .RE |
| .PP |
| \-\-is\-shallow\-repository |
| .RS 4 |
| When the repository is shallow print "true", otherwise "false"\&. |
| .RE |
| .PP |
| \-\-resolve\-git\-dir <path> |
| .RS 4 |
| Check if <path> is a valid repository or a gitfile that points at a valid repository, and print the location of the repository\&. If <path> is a gitfile then the resolved path to the real repository is printed\&. |
| .RE |
| .PP |
| \-\-git\-path <path> |
| .RS 4 |
| Resolve "$GIT_DIR/<path>" and takes other path relocation variables such as $GIT_OBJECT_DIRECTORY, $GIT_INDEX_FILE\&... into account\&. For example, if $GIT_OBJECT_DIRECTORY is set to /foo/bar then "git rev\-parse \-\-git\-path objects/abc" returns /foo/bar/abc\&. |
| .RE |
| .PP |
| \-\-show\-cdup |
| .RS 4 |
| 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)\&. |
| .RE |
| .PP |
| \-\-show\-prefix |
| .RS 4 |
| When the command is invoked from a subdirectory, show the path of the current directory relative to the top\-level directory\&. |
| .RE |
| .PP |
| \-\-show\-toplevel |
| .RS 4 |
| Show the absolute path of the top\-level directory\&. |
| .RE |
| .PP |
| \-\-show\-superproject\-working\-tree |
| .RS 4 |
| Show the absolute path of the root of the superproject\(cqs working tree (if exists) that uses the current repository as its submodule\&. Outputs nothing if the current repository is not used as a submodule by any project\&. |
| .RE |
| .PP |
| \-\-shared\-index\-path |
| .RS 4 |
| Show the path to the shared index file in split index mode, or empty if not in split\-index mode\&. |
| .RE |
| .SS "Other Options" |
| .PP |
| \-\-since=datestring, \-\-after=datestring |
| .RS 4 |
| Parse the date string, and output the corresponding \-\-max\-age= parameter for |
| \fIgit rev\-list\fR\&. |
| .RE |
| .PP |
| \-\-until=datestring, \-\-before=datestring |
| .RS 4 |
| Parse the date string, and output the corresponding \-\-min\-age= parameter for |
| \fIgit rev\-list\fR\&. |
| .RE |
| .PP |
| <args>\&... |
| .RS 4 |
| Flags and parameters to be parsed\&. |
| .RE |
| .SH "SPECIFYING REVISIONS" |
| .sp |
| A revision parameter \fI<rev>\fR typically, but not necessarily, names a commit object\&. It uses what is called an \fIextended SHA\-1\fR syntax\&. Here are various ways to spell object names\&. The ones listed near the end of this list name trees and blobs contained in a commit\&. |
| .if n \{\ |
| .sp |
| .\} |
| .RS 4 |
| .it 1 an-trap |
| .nr an-no-space-flag 1 |
| .nr an-break-flag 1 |
| .br |
| .ps +1 |
| \fBNote\fR |
| .ps -1 |
| .br |
| .sp |
| This document shows the "raw" syntax as seen by git\&. The shell and other UIs might require additional quoting to protect special characters and to avoid word splitting\&. |
| .sp .5v |
| .RE |
| .PP |
| \fI<sha1>\fR, e\&.g\&. \fIdae86e1950b1277e545cee180551750029cfe735\fR, \fIdae86e\fR |
| .RS 4 |
| The full SHA\-1 object name (40\-byte hexadecimal string), or a leading substring that is unique within the repository\&. E\&.g\&. dae86e1950b1277e545cee180551750029cfe735 and dae86e both name the same commit object if there is no other object in your repository whose object name starts with dae86e\&. |
| .RE |
| .PP |
| \fI<describeOutput>\fR, e\&.g\&. \fIv1\&.7\&.4\&.2\-679\-g3bee7fb\fR |
| .RS 4 |
| Output from |
| \fBgit describe\fR; i\&.e\&. a closest tag, optionally followed by a dash and a number of commits, followed by a dash, a |
| \fIg\fR, and an abbreviated object name\&. |
| .RE |
| .PP |
| \fI<refname>\fR, e\&.g\&. \fImaster\fR, \fIheads/master\fR, \fIrefs/heads/master\fR |
| .RS 4 |
| A symbolic ref name\&. E\&.g\&. |
| \fImaster\fR |
| typically means the commit object referenced by |
| \fIrefs/heads/master\fR\&. If you happen to have both |
| \fIheads/master\fR |
| and |
| \fItags/master\fR, you can explicitly say |
| \fIheads/master\fR |
| to tell Git which one you mean\&. When ambiguous, a |
| \fI<refname>\fR |
| is disambiguated by taking the first match in the following rules: |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04' 1.\h'+01'\c |
| .\} |
| .el \{\ |
| .sp -1 |
| .IP " 1." 4.2 |
| .\} |
| If |
| \fI$GIT_DIR/<refname>\fR |
| exists, that is what you mean (this is usually useful only for |
| \fBHEAD\fR, |
| \fBFETCH_HEAD\fR, |
| \fBORIG_HEAD\fR, |
| \fBMERGE_HEAD\fR |
| and |
| \fBCHERRY_PICK_HEAD\fR); |
| .RE |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04' 2.\h'+01'\c |
| .\} |
| .el \{\ |
| .sp -1 |
| .IP " 2." 4.2 |
| .\} |
| otherwise, |
| \fIrefs/<refname>\fR |
| if it exists; |
| .RE |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04' 3.\h'+01'\c |
| .\} |
| .el \{\ |
| .sp -1 |
| .IP " 3." 4.2 |
| .\} |
| otherwise, |
| \fIrefs/tags/<refname>\fR |
| if it exists; |
| .RE |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04' 4.\h'+01'\c |
| .\} |
| .el \{\ |
| .sp -1 |
| .IP " 4." 4.2 |
| .\} |
| otherwise, |
| \fIrefs/heads/<refname>\fR |
| if it exists; |
| .RE |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04' 5.\h'+01'\c |
| .\} |
| .el \{\ |
| .sp -1 |
| .IP " 5." 4.2 |
| .\} |
| otherwise, |
| \fIrefs/remotes/<refname>\fR |
| if it exists; |
| .RE |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04' 6.\h'+01'\c |
| .\} |
| .el \{\ |
| .sp -1 |
| .IP " 6." 4.2 |
| .\} |
| otherwise, |
| \fIrefs/remotes/<refname>/HEAD\fR |
| if it exists\&. |
| .sp |
| \fBHEAD\fR |
| names the commit on which you based the changes in the working tree\&. |
| \fBFETCH_HEAD\fR |
| records the branch which you fetched from a remote repository with your last |
| \fBgit fetch\fR |
| invocation\&. |
| \fBORIG_HEAD\fR |
| is created by commands that move your |
| \fBHEAD\fR |
| in a drastic way, to record the position of the |
| \fBHEAD\fR |
| before their operation, so that you can easily change the tip of the branch back to the state before you ran them\&. |
| \fBMERGE_HEAD\fR |
| records the commit(s) which you are merging into your branch when you run |
| \fBgit merge\fR\&. |
| \fBCHERRY_PICK_HEAD\fR |
| records the commit which you are cherry\-picking when you run |
| \fBgit cherry\-pick\fR\&. |
| .sp |
| Note that any of the |
| \fIrefs/*\fR |
| cases above may come either from the |
| \fI$GIT_DIR/refs\fR |
| directory or from the |
| \fI$GIT_DIR/packed\-refs\fR |
| file\&. While the ref name encoding is unspecified, UTF\-8 is preferred as some output processing may assume ref names in UTF\-8\&. |
| .RE |
| .RE |
| .PP |
| \fI@\fR |
| .RS 4 |
| \fI@\fR |
| alone is a shortcut for |
| \fBHEAD\fR\&. |
| .RE |
| .PP |
| \fI<refname>@{<date>}\fR, e\&.g\&. \fImaster@{yesterday}\fR, \fIHEAD@{5 minutes ago}\fR |
| .RS 4 |
| A ref followed by the suffix |
| \fI@\fR |
| with a date specification enclosed in a brace pair (e\&.g\&. |
| \fI{yesterday}\fR, |
| \fI{1 month 2 weeks 3 days 1 hour 1 second ago}\fR |
| or |
| \fI{1979\-02\-26 18:30:00}\fR) specifies the value of the ref at a prior point in time\&. This suffix may only be used immediately following a ref name and the ref must have an existing log (\fI$GIT_DIR/logs/<ref>\fR)\&. Note that this looks up the state of your |
| \fBlocal\fR |
| ref at a given time; e\&.g\&., what was in your local |
| \fImaster\fR |
| branch last week\&. If you want to look at commits made during certain times, see |
| \fB\-\-since\fR |
| and |
| \fB\-\-until\fR\&. |
| .RE |
| .PP |
| \fI<refname>@{<n>}\fR, e\&.g\&. \fImaster@{1}\fR |
| .RS 4 |
| A ref followed by the suffix |
| \fI@\fR |
| with an ordinal specification enclosed in a brace pair (e\&.g\&. |
| \fI{1}\fR, |
| \fI{15}\fR) specifies the n\-th prior value of that ref\&. For example |
| \fImaster@{1}\fR |
| is the immediate prior value of |
| \fImaster\fR |
| while |
| \fImaster@{5}\fR |
| is the 5th prior value of |
| \fImaster\fR\&. This suffix may only be used immediately following a ref name and the ref must have an existing log (\fI$GIT_DIR/logs/<refname>\fR)\&. |
| .RE |
| .PP |
| \fI@{<n>}\fR, e\&.g\&. \fI@{1}\fR |
| .RS 4 |
| You can use the |
| \fI@\fR |
| construct with an empty ref part to get at a reflog entry of the current branch\&. For example, if you are on branch |
| \fIblabla\fR |
| then |
| \fI@{1}\fR |
| means the same as |
| \fIblabla@{1}\fR\&. |
| .RE |
| .PP |
| \fI@{\-<n>}\fR, e\&.g\&. \fI@{\-1}\fR |
| .RS 4 |
| The construct |
| \fI@{\-<n>}\fR |
| means the <n>th branch/commit checked out before the current one\&. |
| .RE |
| .PP |
| \fI<branchname>@{upstream}\fR, e\&.g\&. \fImaster@{upstream}\fR, \fI@{u}\fR |
| .RS 4 |
| The suffix |
| \fI@{upstream}\fR |
| to a branchname (short form |
| \fI<branchname>@{u}\fR) refers to the branch that the branch specified by branchname is set to build on top of (configured with |
| \fBbranch\&.<name>\&.remote\fR |
| and |
| \fBbranch\&.<name>\&.merge\fR)\&. A missing branchname defaults to the current one\&. These suffixes are also accepted when spelled in uppercase, and they mean the same thing no matter the case\&. |
| .RE |
| .PP |
| \fI<branchname>@{push}\fR, e\&.g\&. \fImaster@{push}\fR, \fI@{push}\fR |
| .RS 4 |
| The suffix |
| \fI@{push}\fR |
| reports the branch "where we would push to" if |
| \fBgit push\fR |
| were run while |
| \fBbranchname\fR |
| was checked out (or the current |
| \fBHEAD\fR |
| if no branchname is specified)\&. Since our push destination is in a remote repository, of course, we report the local tracking branch that corresponds to that branch (i\&.e\&., something in |
| \fIrefs/remotes/\fR)\&. |
| .sp |
| Here\(cqs an example to make it more clear: |
| .sp |
| .if n \{\ |
| .RS 4 |
| .\} |
| .nf |
| $ git config push\&.default current |
| $ git config remote\&.pushdefault myfork |
| $ git checkout \-b mybranch origin/master |
| |
| $ git rev\-parse \-\-symbolic\-full\-name @{upstream} |
| refs/remotes/origin/master |
| |
| $ git rev\-parse \-\-symbolic\-full\-name @{push} |
| refs/remotes/myfork/mybranch |
| .fi |
| .if n \{\ |
| .RE |
| .\} |
| .sp |
| Note in the example that we set up a triangular workflow, where we pull from one location and push to another\&. In a non\-triangular workflow, |
| \fI@{push}\fR |
| is the same as |
| \fI@{upstream}\fR, and there is no need for it\&. |
| .sp |
| This suffix is also accepted when spelled in uppercase, and means the same thing no matter the case\&. |
| .RE |
| .PP |
| \fI<rev>^\fR, e\&.g\&. \fIHEAD^, v1\&.5\&.1^0\fR |
| .RS 4 |
| A suffix |
| \fI^\fR |
| to a revision parameter means the first parent of that commit object\&. |
| \fI^<n>\fR |
| means the <n>th parent (i\&.e\&. |
| \fI<rev>^\fR |
| is equivalent to |
| \fI<rev>^1\fR)\&. As a special rule, |
| \fI<rev>^0\fR |
| means the commit itself and is used when |
| \fI<rev>\fR |
| is the object name of a tag object that refers to a commit object\&. |
| .RE |
| .PP |
| \fI<rev>~<n>\fR, e\&.g\&. \fImaster~3\fR |
| .RS 4 |
| A suffix |
| \fI~<n>\fR |
| to a revision parameter means the commit object that is the <n>th generation ancestor of the named commit object, following only the first parents\&. I\&.e\&. |
| \fI<rev>~3\fR |
| is equivalent to |
| \fI<rev>^^^\fR |
| which is equivalent to |
| \fI<rev>^1^1^1\fR\&. See below for an illustration of the usage of this form\&. |
| .RE |
| .PP |
| \fI<rev>^{<type>}\fR, e\&.g\&. \fIv0\&.99\&.8^{commit}\fR |
| .RS 4 |
| A suffix |
| \fI^\fR |
| followed by an object type name enclosed in brace pair means dereference the object at |
| \fI<rev>\fR |
| recursively until an object of type |
| \fI<type>\fR |
| is found or the object cannot be dereferenced anymore (in which case, barf)\&. For example, if |
| \fI<rev>\fR |
| is a commit\-ish, |
| \fI<rev>^{commit}\fR |
| describes the corresponding commit object\&. Similarly, if |
| \fI<rev>\fR |
| is a tree\-ish, |
| \fI<rev>^{tree}\fR |
| describes the corresponding tree object\&. |
| \fI<rev>^0\fR |
| is a short\-hand for |
| \fI<rev>^{commit}\fR\&. |
| .sp |
| \fIrev^{object}\fR |
| can be used to make sure |
| \fIrev\fR |
| names an object that exists, without requiring |
| \fIrev\fR |
| to be a tag, and without dereferencing |
| \fIrev\fR; because a tag is already an object, it does not have to be dereferenced even once to get to an object\&. |
| .sp |
| \fIrev^{tag}\fR |
| can be used to ensure that |
| \fIrev\fR |
| identifies an existing tag object\&. |
| .RE |
| .PP |
| \fI<rev>^{}\fR, e\&.g\&. \fIv0\&.99\&.8^{}\fR |
| .RS 4 |
| A suffix |
| \fI^\fR |
| followed by an empty brace pair means the object could be a tag, and dereference the tag recursively until a non\-tag object is found\&. |
| .RE |
| .PP |
| \fI<rev>^{/<text>}\fR, e\&.g\&. \fIHEAD^{/fix nasty bug}\fR |
| .RS 4 |
| A suffix |
| \fI^\fR |
| to a revision parameter, followed by a brace pair that contains a text led by a slash, is the same as the |
| \fI:/fix nasty bug\fR |
| syntax below except that it returns the youngest matching commit which is reachable from the |
| \fI<rev>\fR |
| before |
| \fI^\fR\&. |
| .RE |
| .PP |
| \fI:/<text>\fR, e\&.g\&. \fI:/fix nasty bug\fR |
| .RS 4 |
| A colon, followed by a slash, followed by a text, names a commit whose commit message matches the specified regular expression\&. This name returns the youngest matching commit which is reachable from any ref, including HEAD\&. The regular expression can match any part of the commit message\&. To match messages starting with a string, one can use e\&.g\&. |
| \fI:/^foo\fR\&. The special sequence |
| \fI:/!\fR |
| is reserved for modifiers to what is matched\&. |
| \fI:/!\-foo\fR |
| performs a negative match, while |
| \fI:/!!foo\fR |
| matches a literal |
| \fI!\fR |
| character, followed by |
| \fIfoo\fR\&. Any other sequence beginning with |
| \fI:/!\fR |
| is reserved for now\&. Depending on the given text, the shell\(cqs word splitting rules might require additional quoting\&. |
| .RE |
| .PP |
| \fI<rev>:<path>\fR, e\&.g\&. \fIHEAD:README\fR, \fI:README\fR, \fImaster:\&./README\fR |
| .RS 4 |
| A suffix |
| \fI:\fR |
| followed by a path names the blob or tree at the given path in the tree\-ish object named by the part before the colon\&. |
| \fI:path\fR |
| (with an empty part before the colon) is a special case of the syntax described next: content recorded in the index at the given path\&. A path starting with |
| \fI\&./\fR |
| or |
| \fI\&.\&./\fR |
| is relative to the current working directory\&. The given path will be converted to be relative to the working tree\(cqs root directory\&. This is most useful to address a blob or tree from a commit or tree that has the same tree structure as the working tree\&. |
| .RE |
| .PP |
| \fI:<n>:<path>\fR, e\&.g\&. \fI:0:README\fR, \fI:README\fR |
| .RS 4 |
| A colon, optionally followed by a stage number (0 to 3) and a colon, followed by a path, names a blob object in the index at the given path\&. A missing stage number (and the colon that follows it) names a stage 0 entry\&. During a merge, stage 1 is the common ancestor, stage 2 is the target branch\(cqs version (typically the current branch), and stage 3 is the version from the branch which is being merged\&. |
| .RE |
| .sp |
| Here is an illustration, by Jon Loeliger\&. Both commit nodes B and C are parents of commit node A\&. Parent commits are ordered left\-to\-right\&. |
| .sp |
| .if n \{\ |
| .RS 4 |
| .\} |
| .nf |
| G H I J |
| \e / \e / |
| D E F |
| \e | / \e |
| \e | / | |
| \e|/ | |
| B C |
| \e / |
| \e / |
| A |
| .fi |
| .if n \{\ |
| .RE |
| .\} |
| .sp |
| .if n \{\ |
| .RS 4 |
| .\} |
| .nf |
| A = = A^0 |
| B = A^ = A^1 = A~1 |
| C = A^2 = A^2 |
| D = A^^ = A^1^1 = A~2 |
| E = B^2 = A^^2 |
| F = B^3 = A^^3 |
| G = A^^^ = A^1^1^1 = A~3 |
| H = D^2 = B^^2 = A^^^2 = A~2^2 |
| I = F^ = B^3^ = A^^3^ |
| J = F^2 = B^3^2 = A^^3^2 |
| .fi |
| .if n \{\ |
| .RE |
| .\} |
| .SH "SPECIFYING RANGES" |
| .sp |
| History traversing commands such as \fBgit log\fR operate on a set of commits, not just a single commit\&. |
| .sp |
| For these commands, specifying a single revision, using the notation described in the previous section, means the set of commits \fBreachable\fR from the given commit\&. |
| .sp |
| A commit\(cqs reachable set is the commit itself and the commits in its ancestry chain\&. |
| .SS "Commit Exclusions" |
| .PP |
| \fI^<rev>\fR (caret) Notation |
| .RS 4 |
| To exclude commits reachable from a commit, a prefix |
| \fI^\fR |
| notation is used\&. E\&.g\&. |
| \fI^r1 r2\fR |
| means commits reachable from |
| \fIr2\fR |
| but exclude the ones reachable from |
| \fIr1\fR |
| (i\&.e\&. |
| \fIr1\fR |
| and its ancestors)\&. |
| .RE |
| .SS "Dotted Range Notations" |
| .PP |
| The \fI\&.\&.\fR (two\-dot) Range Notation |
| .RS 4 |
| The |
| \fI^r1 r2\fR |
| set operation appears so often that there is a shorthand for it\&. When you have two commits |
| \fIr1\fR |
| and |
| \fIr2\fR |
| (named according to the syntax explained in SPECIFYING REVISIONS above), you can ask for commits that are reachable from r2 excluding those that are reachable from r1 by |
| \fI^r1 r2\fR |
| and it can be written as |
| \fIr1\&.\&.r2\fR\&. |
| .RE |
| .PP |
| The \fI\&...\fR (three\-dot) Symmetric Difference Notation |
| .RS 4 |
| A similar notation |
| \fIr1\&.\&.\&.r2\fR |
| is called symmetric difference of |
| \fIr1\fR |
| and |
| \fIr2\fR |
| and is defined as |
| \fIr1 r2 \-\-not $(git merge\-base \-\-all r1 r2)\fR\&. It is the set of commits that are reachable from either one of |
| \fIr1\fR |
| (left side) or |
| \fIr2\fR |
| (right side) but not from both\&. |
| .RE |
| .sp |
| In these two shorthand notations, you can omit one end and let it default to HEAD\&. For example, \fIorigin\&.\&.\fR is a shorthand for \fIorigin\&.\&.HEAD\fR and asks "What did I do since I forked from the origin branch?" Similarly, \fI\&.\&.origin\fR is a shorthand for \fIHEAD\&.\&.origin\fR and asks "What did the origin do since I forked from them?" Note that \fI\&.\&.\fR would mean \fIHEAD\&.\&.HEAD\fR which is an empty range that is both reachable and unreachable from HEAD\&. |
| .SS "Other <rev>^ Parent Shorthand Notations" |
| .sp |
| Three other shorthands exist, particularly useful for merge commits, for naming a set that is formed by a commit and its parent commits\&. |
| .sp |
| The \fIr1^@\fR notation means all parents of \fIr1\fR\&. |
| .sp |
| The \fIr1^!\fR notation includes commit \fIr1\fR but excludes all of its parents\&. By itself, this notation denotes the single commit \fIr1\fR\&. |
| .sp |
| The \fI<rev>^\-<n>\fR notation includes \fI<rev>\fR but excludes the <n>th parent (i\&.e\&. a shorthand for \fI<rev>^<n>\&.\&.<rev>\fR), with \fI<n>\fR = 1 if not given\&. This is typically useful for merge commits where you can just pass \fI<commit>^\-\fR to get all the commits in the branch that was merged in merge commit \fI<commit>\fR (including \fI<commit>\fR itself)\&. |
| .sp |
| While \fI<rev>^<n>\fR was about specifying a single commit parent, these three notations also consider its parents\&. For example you can say \fIHEAD^2^@\fR, however you cannot say \fIHEAD^@^2\fR\&. |
| .SH "REVISION RANGE SUMMARY" |
| .PP |
| \fI<rev>\fR |
| .RS 4 |
| Include commits that are reachable from <rev> (i\&.e\&. <rev> and its ancestors)\&. |
| .RE |
| .PP |
| \fI^<rev>\fR |
| .RS 4 |
| Exclude commits that are reachable from <rev> (i\&.e\&. <rev> and its ancestors)\&. |
| .RE |
| .PP |
| \fI<rev1>\&.\&.<rev2>\fR |
| .RS 4 |
| Include commits that are reachable from <rev2> but exclude those that are reachable from <rev1>\&. When either <rev1> or <rev2> is omitted, it defaults to |
| \fBHEAD\fR\&. |
| .RE |
| .PP |
| \fI<rev1>\&.\&.\&.<rev2>\fR |
| .RS 4 |
| Include commits that are reachable from either <rev1> or <rev2> but exclude those that are reachable from both\&. When either <rev1> or <rev2> is omitted, it defaults to |
| \fBHEAD\fR\&. |
| .RE |
| .PP |
| \fI<rev>^@\fR, e\&.g\&. \fIHEAD^@\fR |
| .RS 4 |
| A suffix |
| \fI^\fR |
| followed by an at sign is the same as listing all parents of |
| \fI<rev>\fR |
| (meaning, include anything reachable from its parents, but not the commit itself)\&. |
| .RE |
| .PP |
| \fI<rev>^!\fR, e\&.g\&. \fIHEAD^!\fR |
| .RS 4 |
| A suffix |
| \fI^\fR |
| followed by an exclamation mark is the same as giving commit |
| \fI<rev>\fR |
| and then all its parents prefixed with |
| \fI^\fR |
| to exclude them (and their ancestors)\&. |
| .RE |
| .PP |
| \fI<rev>^\-<n>\fR, e\&.g\&. \fIHEAD^\-, HEAD^\-2\fR |
| .RS 4 |
| Equivalent to |
| \fI<rev>^<n>\&.\&.<rev>\fR, with |
| \fI<n>\fR |
| = 1 if not given\&. |
| .RE |
| .sp |
| Here are a handful of examples using the Loeliger illustration above, with each step in the notation\(cqs expansion and selection carefully spelt out: |
| .sp |
| .if n \{\ |
| .RS 4 |
| .\} |
| .nf |
| Args Expanded arguments Selected commits |
| D G H D |
| D F G H I J D F |
| ^G D H D |
| ^D B E I J F B |
| ^D B C E I J F B C |
| C I J F C |
| B\&.\&.C = ^B C C |
| B\&.\&.\&.C = B ^F C G H D E B C |
| B^\- = B^\&.\&.B |
| = ^B^1 B E I J F B |
| C^@ = C^1 |
| = F I J F |
| B^@ = B^1 B^2 B^3 |
| = D E F D G H E F I J |
| C^! = C ^C^@ |
| = C ^C^1 |
| = C ^F C |
| B^! = B ^B^@ |
| = B ^B^1 ^B^2 ^B^3 |
| = B ^D ^E ^F B |
| F^! D = F ^I ^J D G H D F |
| .fi |
| .if n \{\ |
| .RE |
| .\} |
| .SH "PARSEOPT" |
| .sp |
| In \fB\-\-parseopt\fR mode, \fIgit rev\-parse\fR 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 \fBgetopt(1)\fR does\&. |
| .sp |
| 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 \fBsh(1)\fR \fBeval\fR to replace the arguments with normalized ones\&. In case of error, it outputs usage on the standard error stream, and exits with code 129\&. |
| .sp |
| Note: Make sure you quote the result when passing it to \fBeval\fR\&. See below for an example\&. |
| .SS "Input Format" |
| .sp |
| \fIgit rev\-parse \-\-parseopt\fR input format is fully text based\&. It has two parts, separated by a line that contains only \fB\-\-\fR\&. The lines before the separator (should be one or more) are used for the usage\&. The lines after the separator describe the options\&. |
| .sp |
| Each line of options has this format: |
| .sp |
| .if n \{\ |
| .RS 4 |
| .\} |
| .nf |
| <opt\-spec><flags>*<arg\-hint>? SP+ help LF |
| .fi |
| .if n \{\ |
| .RE |
| .\} |
| .sp |
| |
| .PP |
| \fB<opt\-spec>\fR |
| .RS 4 |
| 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\&. May not contain any of the |
| \fB<flags>\fR |
| characters\&. |
| \fBh,help\fR, |
| \fBdry\-run\fR |
| and |
| \fBf\fR |
| are examples of correct |
| \fB<opt\-spec>\fR\&. |
| .RE |
| .PP |
| \fB<flags>\fR |
| .RS 4 |
| \fB<flags>\fR |
| are of |
| \fB*\fR, |
| \fB=\fR, |
| \fB?\fR |
| or |
| \fB!\fR\&. |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04'\(bu\h'+03'\c |
| .\} |
| .el \{\ |
| .sp -1 |
| .IP \(bu 2.3 |
| .\} |
| Use |
| \fB=\fR |
| if the option takes an argument\&. |
| .RE |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04'\(bu\h'+03'\c |
| .\} |
| .el \{\ |
| .sp -1 |
| .IP \(bu 2.3 |
| .\} |
| Use |
| \fB?\fR |
| to mean that the option takes an optional argument\&. You probably want to use the |
| \fB\-\-stuck\-long\fR |
| mode to be able to unambiguously parse the optional argument\&. |
| .RE |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04'\(bu\h'+03'\c |
| .\} |
| .el \{\ |
| .sp -1 |
| .IP \(bu 2.3 |
| .\} |
| Use |
| \fB*\fR |
| to mean that this option should not be listed in the usage generated for the |
| \fB\-h\fR |
| argument\&. It\(cqs shown for |
| \fB\-\-help\-all\fR |
| as documented in |
| \fBgitcli\fR(7)\&. |
| .RE |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04'\(bu\h'+03'\c |
| .\} |
| .el \{\ |
| .sp -1 |
| .IP \(bu 2.3 |
| .\} |
| Use |
| \fB!\fR |
| to not make the corresponding negated long option available\&. |
| .RE |
| .RE |
| .PP |
| \fB<arg\-hint>\fR |
| .RS 4 |
| \fB<arg\-hint>\fR, if specified, is used as a name of the argument in the help output, for options that take arguments\&. |
| \fB<arg\-hint>\fR |
| is terminated by the first whitespace\&. It is customary to use a dash to separate words in a multi\-word argument hint\&. |
| .RE |
| .sp |
| The remainder of the line, after stripping the spaces, is used as the help associated to the option\&. |
| .sp |
| Blank lines are ignored, and lines that don\(cqt match this specification are used as option group headers (start the line with a space to create such lines on purpose)\&. |
| .SS "Example" |
| .sp |
| .if n \{\ |
| .RS 4 |
| .\} |
| .nf |
| OPTS_SPEC="\e |
| 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 |
| baz=arg another cool option \-\-baz with a named argument |
| qux?path qux may take a path argument but has meaning by itself |
| |
| An option group Header |
| C? option C with an optional argument" |
| |
| eval "$(echo "$OPTS_SPEC" | git rev\-parse \-\-parseopt \-\- "$@" || echo exit $?)" |
| .fi |
| .if n \{\ |
| .RE |
| .\} |
| .sp |
| .SS "Usage text" |
| .sp |
| When \fB"$@"\fR is \fB\-h\fR or \fB\-\-help\fR in the above example, the following usage text would be shown: |
| .sp |
| .if n \{\ |
| .RS 4 |
| .\} |
| .nf |
| usage: 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 |
| \-\-baz <arg> another cool option \-\-baz with a named argument |
| \-\-qux[=<path>] qux may take a path argument but has meaning by itself |
| |
| An option group Header |
| \-C[\&.\&.\&.] option C with an optional argument |
| .fi |
| .if n \{\ |
| .RE |
| .\} |
| .sp |
| .SH "SQ\-QUOTE" |
| .sp |
| In \fB\-\-sq\-quote\fR mode, \fIgit rev\-parse\fR echoes on the standard output a single line suitable for \fBsh(1)\fR \fBeval\fR\&. This line is made by normalizing the arguments following \fB\-\-sq\-quote\fR\&. Nothing other than quoting the arguments is done\&. |
| .sp |
| If you want command input to still be interpreted as usual by \fIgit rev\-parse\fR before the output is shell quoted, see the \fB\-\-sq\fR option\&. |
| .SS "Example" |
| .sp |
| .if n \{\ |
| .RS 4 |
| .\} |
| .nf |
| $ cat >your\-git\-script\&.sh <<\eEOF |
| #!/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\(aqc" |
| .fi |
| .if n \{\ |
| .RE |
| .\} |
| .sp |
| .SH "EXAMPLES" |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04'\(bu\h'+03'\c |
| .\} |
| .el \{\ |
| .sp -1 |
| .IP \(bu 2.3 |
| .\} |
| Print the object name of the current commit: |
| .sp |
| .if n \{\ |
| .RS 4 |
| .\} |
| .nf |
| $ git rev\-parse \-\-verify HEAD |
| .fi |
| .if n \{\ |
| .RE |
| .\} |
| .sp |
| .RE |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04'\(bu\h'+03'\c |
| .\} |
| .el \{\ |
| .sp -1 |
| .IP \(bu 2.3 |
| .\} |
| Print the commit object name from the revision in the $REV shell variable: |
| .sp |
| .if n \{\ |
| .RS 4 |
| .\} |
| .nf |
| $ git rev\-parse \-\-verify $REV^{commit} |
| .fi |
| .if n \{\ |
| .RE |
| .\} |
| .sp |
| This will error out if $REV is empty or not a valid revision\&. |
| .RE |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04'\(bu\h'+03'\c |
| .\} |
| .el \{\ |
| .sp -1 |
| .IP \(bu 2.3 |
| .\} |
| Similar to above: |
| .sp |
| .if n \{\ |
| .RS 4 |
| .\} |
| .nf |
| $ git rev\-parse \-\-default master \-\-verify $REV |
| .fi |
| .if n \{\ |
| .RE |
| .\} |
| .sp |
| but if $REV is empty, the commit object name from master will be printed\&. |
| .RE |
| .SH "GIT" |
| .sp |
| Part of the \fBgit\fR(1) suite |