Junio C Hamano | 7fc9d69 | 2005-08-23 01:49:47 -0700 | [diff] [blame] | 1 | git-rev-parse(1) |
| 2 | ================ |
| 3 | |
| 4 | NAME |
| 5 | ---- |
Fredrik Kuivinen | 7bd7f28 | 2006-03-09 17:24:50 +0100 | [diff] [blame] | 6 | git-rev-parse - Pick out and massage parameters |
Junio C Hamano | 7fc9d69 | 2005-08-23 01:49:47 -0700 | [diff] [blame] | 7 | |
| 8 | |
| 9 | SYNOPSIS |
| 10 | -------- |
Martin von Zweigbergk | 7791a1d | 2011-07-01 22:38:26 -0400 | [diff] [blame] | 11 | [verse] |
Jonathan Nieder | b1889c3 | 2008-06-30 01:09:04 -0500 | [diff] [blame] | 12 | 'git rev-parse' [ --option ] <args>... |
Junio C Hamano | 7fc9d69 | 2005-08-23 01:49:47 -0700 | [diff] [blame] | 13 | |
| 14 | DESCRIPTION |
| 15 | ----------- |
Junio C Hamano | 5077fa9 | 2005-09-07 14:08:38 -0700 | [diff] [blame] | 16 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 17 | Many Git porcelainish commands take mixture of flags |
Junio C Hamano | 5077fa9 | 2005-09-07 14:08:38 -0700 | [diff] [blame] | 18 | (i.e. parameters that begin with a dash '-') and parameters |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 19 | meant for the underlying 'git rev-list' command they use internally |
Jonathan Nieder | 483bc4f | 2008-06-30 13:56:34 -0500 | [diff] [blame] | 20 | and flags and parameters for the other commands they use |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 21 | downstream of 'git rev-list'. This command is used to |
Junio C Hamano | 5077fa9 | 2005-09-07 14:08:38 -0700 | [diff] [blame] | 22 | distinguish between them. |
Junio C Hamano | 7fc9d69 | 2005-08-23 01:49:47 -0700 | [diff] [blame] | 23 | |
| 24 | |
| 25 | OPTIONS |
| 26 | ------- |
John Keeping | 49c6391 | 2013-07-21 13:49:27 +0100 | [diff] [blame] | 27 | |
| 28 | Operation Modes |
| 29 | ~~~~~~~~~~~~~~~ |
| 30 | |
| 31 | Each of these options must appear first on the command line. |
| 32 | |
Pierre Habouzit | 21d4783 | 2007-11-04 11:30:53 +0100 | [diff] [blame] | 33 | --parseopt:: |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 34 | Use 'git rev-parse' in option parsing mode (see PARSEOPT section below). |
Pierre Habouzit | 21d4783 | 2007-11-04 11:30:53 +0100 | [diff] [blame] | 35 | |
John Keeping | 49c6391 | 2013-07-21 13:49:27 +0100 | [diff] [blame] | 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 | |
| 41 | Options for --parseopt |
| 42 | ~~~~~~~~~~~~~~~~~~~~~~ |
| 43 | |
Uwe Kleine-König | 2163e3f7 | 2009-04-28 22:29:24 +0200 | [diff] [blame] | 44 | --keep-dashdash:: |
Pierre Habouzit | 21d4783 | 2007-11-04 11:30:53 +0100 | [diff] [blame] | 45 | Only meaningful in `--parseopt` mode. Tells the option parser to echo |
| 46 | out the first `--` met instead of skipping it. |
| 47 | |
Uwe Kleine-König | 6e0800e | 2009-06-14 01:58:43 +0200 | [diff] [blame] | 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 |
Ralf Wildenhues | 6a5d0b0 | 2010-01-31 14:24:39 +0100 | [diff] [blame] | 51 | that take options themselves. |
Uwe Kleine-König | 6e0800e | 2009-06-14 01:58:43 +0200 | [diff] [blame] | 52 | |
Nicolas Vigier | f8c8721 | 2013-10-31 12:08:29 +0100 | [diff] [blame] | 53 | --stuck-long:: |
| 54 | Only meaningful in `--parseopt` mode. Output the options in their |
| 55 | long form if available, and with their arguments stuck. |
| 56 | |
John Keeping | 49c6391 | 2013-07-21 13:49:27 +0100 | [diff] [blame] | 57 | Options for Filtering |
| 58 | ~~~~~~~~~~~~~~~~~~~~~ |
Christian Couder | 5032537 | 2009-04-25 06:55:26 +0200 | [diff] [blame] | 59 | |
Junio C Hamano | 5077fa9 | 2005-09-07 14:08:38 -0700 | [diff] [blame] | 60 | --revs-only:: |
| 61 | Do not output flags and parameters not meant for |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 62 | 'git rev-list' command. |
Junio C Hamano | 5077fa9 | 2005-09-07 14:08:38 -0700 | [diff] [blame] | 63 | |
| 64 | --no-revs:: |
| 65 | Do not output flags and parameters meant for |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 66 | 'git rev-list' command. |
Junio C Hamano | 5077fa9 | 2005-09-07 14:08:38 -0700 | [diff] [blame] | 67 | |
| 68 | --flags:: |
| 69 | Do not output non-flag parameters. |
| 70 | |
| 71 | --no-flags:: |
| 72 | Do not output flag parameters. |
| 73 | |
John Keeping | 49c6391 | 2013-07-21 13:49:27 +0100 | [diff] [blame] | 74 | Options for Output |
| 75 | ~~~~~~~~~~~~~~~~~~ |
| 76 | |
Junio C Hamano | 5077fa9 | 2005-09-07 14:08:38 -0700 | [diff] [blame] | 77 | --default <arg>:: |
| 78 | If there is no parameter given by the user, use `<arg>` |
| 79 | instead. |
| 80 | |
John Keeping | 12b9d32 | 2013-06-16 15:18:17 +0100 | [diff] [blame] | 81 | --prefix <arg>:: |
| 82 | Behave as if 'git rev-parse' was invoked from the `<arg>` |
| 83 | subdirectory of the working tree. Any relative filenames are |
| 84 | resolved as if they are prefixed by `<arg>` and will be printed |
| 85 | in that form. |
| 86 | + |
| 87 | This can be used to convert arguments to a command run in a subdirectory |
| 88 | so that they can still be used after moving to the top-level of the |
| 89 | repository. For example: |
| 90 | + |
| 91 | ---- |
| 92 | prefix=$(git rev-parse --show-prefix) |
| 93 | cd "$(git rev-parse --show-toplevel)" |
| 94 | eval "set -- $(git rev-parse --sq --prefix "$prefix" "$@")" |
| 95 | ---- |
| 96 | |
Junio C Hamano | 5077fa9 | 2005-09-07 14:08:38 -0700 | [diff] [blame] | 97 | --verify:: |
Michael Haggerty | 2db6067 | 2013-03-30 07:44:25 +0100 | [diff] [blame] | 98 | Verify that exactly one parameter is provided, and that it |
| 99 | can be turned into a raw 20-byte SHA-1 that can be used to |
| 100 | access the object database. If so, emit it to the standard |
| 101 | output; otherwise, error out. |
| 102 | + |
| 103 | If you want to make sure that the output actually names an object in |
| 104 | your object database and/or can be used as a specific type of object |
Ondřej Bílka | 17b83d7 | 2013-07-22 23:02:23 +0200 | [diff] [blame] | 105 | you require, you can add "^{type}" peeling operator to the parameter. |
Michael Haggerty | 2db6067 | 2013-03-30 07:44:25 +0100 | [diff] [blame] | 106 | For example, `git rev-parse "$VAR^{commit}"` will make sure `$VAR` |
| 107 | names an existing object that is a commit-ish (i.e. a commit, or an |
| 108 | annotated tag that points at a commit). To make sure that `$VAR` |
| 109 | names an existing object of any type, `git rev-parse "$VAR^{object}"` |
| 110 | can be used. |
Junio C Hamano | 5077fa9 | 2005-09-07 14:08:38 -0700 | [diff] [blame] | 111 | |
Stephan Beyer | 3240240 | 2008-06-08 03:36:09 +0200 | [diff] [blame] | 112 | -q:: |
| 113 | --quiet:: |
Christian Couder | b1b3596 | 2008-04-26 13:57:23 +0200 | [diff] [blame] | 114 | Only meaningful in `--verify` mode. Do not output an error |
| 115 | message if the first argument is not a valid object name; |
| 116 | instead exit with non-zero status silently. |
| 117 | |
Junio C Hamano | 5077fa9 | 2005-09-07 14:08:38 -0700 | [diff] [blame] | 118 | --sq:: |
| 119 | Usually the output is made one line per flag and |
| 120 | parameter. This option makes output a single line, |
| 121 | properly quoted for consumption by shell. Useful when |
| 122 | you expect your parameter to contain whitespaces and |
| 123 | newlines (e.g. when using pickaxe `-S` with |
Jonathan Nieder | 4cacbf6 | 2010-08-20 05:35:03 -0500 | [diff] [blame] | 124 | 'git diff-{asterisk}'). In contrast to the `--sq-quote` option, |
Christian Couder | 5032537 | 2009-04-25 06:55:26 +0200 | [diff] [blame] | 125 | the command input is still interpreted as usual. |
Junio C Hamano | 5077fa9 | 2005-09-07 14:08:38 -0700 | [diff] [blame] | 126 | |
| 127 | --not:: |
Jonas Fonseca | babfaba | 2005-10-05 16:56:31 -0700 | [diff] [blame] | 128 | When showing object names, prefix them with '{caret}' and |
| 129 | strip '{caret}' prefix from the object names that already have |
Junio C Hamano | 5077fa9 | 2005-09-07 14:08:38 -0700 | [diff] [blame] | 130 | one. |
| 131 | |
John Keeping | 49c6391 | 2013-07-21 13:49:27 +0100 | [diff] [blame] | 132 | --abbrev-ref[=(strict|loose)]:: |
| 133 | A non-ambiguous short name of the objects name. |
| 134 | The option core.warnAmbiguousRefs is used to select the strict |
| 135 | abbreviation mode. |
| 136 | |
| 137 | --short:: |
| 138 | --short=number:: |
| 139 | Instead of outputting the full SHA-1 values of object names try to |
| 140 | abbreviate them to a shorter unique name. When no length is specified |
| 141 | 7 is used. The minimum length is 4. |
| 142 | |
Junio C Hamano | 5077fa9 | 2005-09-07 14:08:38 -0700 | [diff] [blame] | 143 | --symbolic:: |
Thomas Ackermann | d5fa1f1 | 2013-04-15 19:49:04 +0200 | [diff] [blame] | 144 | Usually the object names are output in SHA-1 form (with |
Jonas Fonseca | babfaba | 2005-10-05 16:56:31 -0700 | [diff] [blame] | 145 | possible '{caret}' prefix); this option makes them output in a |
Junio C Hamano | 5077fa9 | 2005-09-07 14:08:38 -0700 | [diff] [blame] | 146 | form as close to the original input as possible. |
| 147 | |
Junio C Hamano | a6d97d4 | 2008-01-05 12:09:55 -0800 | [diff] [blame] | 148 | --symbolic-full-name:: |
| 149 | This is similar to \--symbolic, but it omits input that |
| 150 | are not refs (i.e. branch or tag names; or more |
| 151 | explicitly disambiguating "heads/master" form, when you |
| 152 | want to name the "master" branch when there is an |
| 153 | unfortunately named tag "master"), and show them as full |
| 154 | refnames (e.g. "refs/heads/master"). |
Junio C Hamano | 5077fa9 | 2005-09-07 14:08:38 -0700 | [diff] [blame] | 155 | |
John Keeping | 49c6391 | 2013-07-21 13:49:27 +0100 | [diff] [blame] | 156 | Options for Objects |
| 157 | ~~~~~~~~~~~~~~~~~~~ |
Junio C Hamano | 957d740 | 2012-07-03 14:21:59 -0700 | [diff] [blame] | 158 | |
Junio C Hamano | 5077fa9 | 2005-09-07 14:08:38 -0700 | [diff] [blame] | 159 | --all:: |
Jeff King | cc1b8d8 | 2010-02-17 20:16:20 -0500 | [diff] [blame] | 160 | Show all refs found in `refs/`. |
Junio C Hamano | 5077fa9 | 2005-09-07 14:08:38 -0700 | [diff] [blame] | 161 | |
Ilari Liusvaara | b09fe97 | 2010-01-20 11:48:26 +0200 | [diff] [blame] | 162 | --branches[=pattern]:: |
Ilari Liusvaara | b09fe97 | 2010-01-20 11:48:26 +0200 | [diff] [blame] | 163 | --tags[=pattern]:: |
Ilari Liusvaara | b09fe97 | 2010-01-20 11:48:26 +0200 | [diff] [blame] | 164 | --remotes[=pattern]:: |
Thomas Rast | e2b53e5 | 2010-01-22 01:21:38 +0100 | [diff] [blame] | 165 | Show all branches, tags, or remote-tracking branches, |
Jeff King | cc1b8d8 | 2010-02-17 20:16:20 -0500 | [diff] [blame] | 166 | respectively (i.e., refs found in `refs/heads`, |
| 167 | `refs/tags`, or `refs/remotes`, respectively). |
Thomas Rast | e2b53e5 | 2010-01-22 01:21:38 +0100 | [diff] [blame] | 168 | + |
| 169 | If a `pattern` is given, only refs matching the given shell glob are |
| 170 | shown. If the pattern does not contain a globbing character (`?`, |
Jeff King | 6cf378f | 2012-04-26 04:51:57 -0400 | [diff] [blame] | 171 | `*`, or `[`), it is turned into a prefix match by appending `/*`. |
Sean | a62be77 | 2006-05-13 21:43:00 -0400 | [diff] [blame] | 172 | |
Thomas Rast | e2b53e5 | 2010-01-22 01:21:38 +0100 | [diff] [blame] | 173 | --glob=pattern:: |
| 174 | Show all refs matching the shell glob pattern `pattern`. If |
| 175 | the pattern does not start with `refs/`, this is automatically |
| 176 | prepended. If the pattern does not contain a globbing |
Jeff King | 6cf378f | 2012-04-26 04:51:57 -0400 | [diff] [blame] | 177 | character (`?`, `*`, or `[`), it is turned into a prefix |
| 178 | match by appending `/*`. |
Sean | a62be77 | 2006-05-13 21:43:00 -0400 | [diff] [blame] | 179 | |
Junio C Hamano | 9dc01bf | 2013-11-01 12:13:01 -0700 | [diff] [blame] | 180 | --exclude=<glob-pattern>:: |
| 181 | Do not include refs matching '<glob-pattern>' that the next `--all`, |
| 182 | `--branches`, `--tags`, `--remotes`, or `--glob` would otherwise |
| 183 | consider. Repetitions of this option accumulate exclusion patterns |
| 184 | up to the next `--all`, `--branches`, `--tags`, `--remotes`, or |
| 185 | `--glob` option (other options or arguments do not clear |
| 186 | accumlated patterns). |
| 187 | + |
| 188 | The patterns given should not begin with `refs/heads`, `refs/tags`, or |
| 189 | `refs/remotes` when applied to `--branches`, `--tags`, or `--remotes`, |
| 190 | respectively, and they must begin with `refs/` when applied to `--glob` |
| 191 | or `--all`. If a trailing '/{asterisk}' is intended, it must be given |
| 192 | explicitly. |
| 193 | |
John Keeping | 49c6391 | 2013-07-21 13:49:27 +0100 | [diff] [blame] | 194 | --disambiguate=<prefix>:: |
| 195 | Show every object whose name begins with the given prefix. |
| 196 | The <prefix> must be at least 4 hexadecimal digits long to |
| 197 | avoid listing each and every object in the repository by |
| 198 | mistake. |
Steven Drake | 7cceca5 | 2010-01-12 11:33:48 +1300 | [diff] [blame] | 199 | |
John Keeping | 49c6391 | 2013-07-21 13:49:27 +0100 | [diff] [blame] | 200 | Options for Files |
| 201 | ~~~~~~~~~~~~~~~~~ |
Junio C Hamano | 7fc9d69 | 2005-08-23 01:49:47 -0700 | [diff] [blame] | 202 | |
John Keeping | 49c6391 | 2013-07-21 13:49:27 +0100 | [diff] [blame] | 203 | --local-env-vars:: |
| 204 | List the GIT_* environment variables that are local to the |
| 205 | repository (e.g. GIT_DIR or GIT_WORK_TREE, but not GIT_EDITOR). |
| 206 | Only the names of the variables are listed, not their value, |
| 207 | even if they are set. |
Junio C Hamano | 5f94c73 | 2005-12-22 22:35:38 -0800 | [diff] [blame] | 208 | |
Jonas Fonseca | 735d80b | 2006-02-18 02:11:36 +0100 | [diff] [blame] | 209 | --git-dir:: |
Jonathan Nieder | 80d868b | 2010-11-26 22:32:31 +0700 | [diff] [blame] | 210 | Show `$GIT_DIR` if defined. Otherwise show the path to |
Jon Seymour | d0740ce | 2012-05-18 19:23:24 +1000 | [diff] [blame] | 211 | the .git directory. The path shown, when relative, is |
| 212 | relative to the current working directory. |
Jonathan Nieder | 80d868b | 2010-11-26 22:32:31 +0700 | [diff] [blame] | 213 | + |
| 214 | If `$GIT_DIR` is not defined and the current directory |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 215 | is not detected to lie in a Git repository or work tree |
Jonathan Nieder | 80d868b | 2010-11-26 22:32:31 +0700 | [diff] [blame] | 216 | print a message to stderr and exit with nonzero status. |
Jonas Fonseca | 735d80b | 2006-02-18 02:11:36 +0100 | [diff] [blame] | 217 | |
Jakub Narebski | c9bf7be | 2007-06-16 21:03:44 +0200 | [diff] [blame] | 218 | --is-inside-git-dir:: |
Matthias Lederhofer | 4faac24 | 2007-06-03 16:46:04 +0200 | [diff] [blame] | 219 | When the current working directory is below the repository |
| 220 | directory print "true", otherwise "false". |
| 221 | |
Matthias Lederhofer | 892c41b | 2007-06-06 09:10:42 +0200 | [diff] [blame] | 222 | --is-inside-work-tree:: |
| 223 | When the current working directory is inside the work tree of the |
| 224 | repository print "true", otherwise "false". |
| 225 | |
Matthias Lederhofer | 493c774 | 2007-06-03 16:46:36 +0200 | [diff] [blame] | 226 | --is-bare-repository:: |
| 227 | When the repository is bare print "true", otherwise "false". |
Jakub Narebski | c9bf7be | 2007-06-16 21:03:44 +0200 | [diff] [blame] | 228 | |
John Keeping | 49c6391 | 2013-07-21 13:49:27 +0100 | [diff] [blame] | 229 | --resolve-git-dir <path>:: |
| 230 | Check if <path> is a valid repository or a gitfile that |
| 231 | points at a valid repository, and print the location of the |
| 232 | repository. If <path> is a gitfile then the resolved path |
| 233 | to the real repository is printed. |
Giuseppe Bilotta | 94c8cca | 2010-02-25 00:34:15 +0100 | [diff] [blame] | 234 | |
John Keeping | 49c6391 | 2013-07-21 13:49:27 +0100 | [diff] [blame] | 235 | --show-cdup:: |
| 236 | When the command is invoked from a subdirectory, show the |
| 237 | path of the top-level directory relative to the current |
| 238 | directory (typically a sequence of "../", or an empty string). |
| 239 | |
| 240 | --show-prefix:: |
| 241 | When the command is invoked from a subdirectory, show the |
| 242 | path of the current directory relative to the top-level |
| 243 | directory. |
| 244 | |
| 245 | --show-toplevel:: |
| 246 | Show the absolute path of the top-level directory. |
| 247 | |
| 248 | Other Options |
| 249 | ~~~~~~~~~~~~~ |
Jonas Fonseca | 735d80b | 2006-02-18 02:11:36 +0100 | [diff] [blame] | 250 | |
Stephan Beyer | 3240240 | 2008-06-08 03:36:09 +0200 | [diff] [blame] | 251 | --since=datestring:: |
| 252 | --after=datestring:: |
Jonathan Nieder | 483bc4f | 2008-06-30 13:56:34 -0500 | [diff] [blame] | 253 | Parse the date string, and output the corresponding |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 254 | --max-age= parameter for 'git rev-list'. |
Junio C Hamano | a3114b3 | 2005-11-02 23:41:25 -0800 | [diff] [blame] | 255 | |
Stephan Beyer | 3240240 | 2008-06-08 03:36:09 +0200 | [diff] [blame] | 256 | --until=datestring:: |
| 257 | --before=datestring:: |
Jonathan Nieder | 483bc4f | 2008-06-30 13:56:34 -0500 | [diff] [blame] | 258 | Parse the date string, and output the corresponding |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 259 | --min-age= parameter for 'git rev-list'. |
Junio C Hamano | a3114b3 | 2005-11-02 23:41:25 -0800 | [diff] [blame] | 260 | |
Junio C Hamano | 7fc9d69 | 2005-08-23 01:49:47 -0700 | [diff] [blame] | 261 | <args>...:: |
Junio C Hamano | 5077fa9 | 2005-09-07 14:08:38 -0700 | [diff] [blame] | 262 | Flags and parameters to be parsed. |
Junio C Hamano | 7fc9d69 | 2005-08-23 01:49:47 -0700 | [diff] [blame] | 263 | |
| 264 | |
Michael J Gruber | 5a8f311 | 2010-07-05 18:11:39 +0200 | [diff] [blame] | 265 | include::revisions.txt[] |
Junio C Hamano | be4c701 | 2006-07-06 22:37:51 -0700 | [diff] [blame] | 266 | |
Pierre Habouzit | 21d4783 | 2007-11-04 11:30:53 +0100 | [diff] [blame] | 267 | PARSEOPT |
| 268 | -------- |
| 269 | |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 270 | In `--parseopt` mode, 'git rev-parse' helps massaging options to bring to shell |
Pierre Habouzit | 21d4783 | 2007-11-04 11:30:53 +0100 | [diff] [blame] | 271 | scripts the same facilities C builtins have. It works as an option normalizer |
| 272 | (e.g. splits single switches aggregate values), a bit like `getopt(1)` does. |
| 273 | |
| 274 | It takes on the standard input the specification of the options to parse and |
Thomas Rast | ac2e1e6 | 2010-07-30 17:01:50 +0200 | [diff] [blame] | 275 | understand, and echoes on the standard output a string suitable for `sh(1)` `eval` |
Pierre Habouzit | 21d4783 | 2007-11-04 11:30:53 +0100 | [diff] [blame] | 276 | to replace the arguments with normalized ones. In case of error, it outputs |
| 277 | usage on the standard error stream, and exits with code 129. |
| 278 | |
Thomas Rast | ac2e1e6 | 2010-07-30 17:01:50 +0200 | [diff] [blame] | 279 | Note: Make sure you quote the result when passing it to `eval`. See |
| 280 | below for an example. |
| 281 | |
Pierre Habouzit | 21d4783 | 2007-11-04 11:30:53 +0100 | [diff] [blame] | 282 | Input Format |
| 283 | ~~~~~~~~~~~~ |
| 284 | |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 285 | 'git rev-parse --parseopt' input format is fully text based. It has two parts, |
Pierre Habouzit | 21d4783 | 2007-11-04 11:30:53 +0100 | [diff] [blame] | 286 | separated by a line that contains only `--`. The lines before the separator |
| 287 | (should be more than one) are used for the usage. |
| 288 | The lines after the separator describe the options. |
| 289 | |
| 290 | Each line of options has this format: |
| 291 | |
| 292 | ------------ |
Pierre Habouzit | ff962a3 | 2008-03-02 09:21:38 +0100 | [diff] [blame] | 293 | <opt_spec><flags>* SP+ help LF |
Pierre Habouzit | 21d4783 | 2007-11-04 11:30:53 +0100 | [diff] [blame] | 294 | ------------ |
| 295 | |
| 296 | `<opt_spec>`:: |
| 297 | its format is the short option character, then the long option name |
| 298 | separated by a comma. Both parts are not required, though at least one |
| 299 | is necessary. `h,help`, `dry-run` and `f` are all three correct |
| 300 | `<opt_spec>`. |
| 301 | |
Pierre Habouzit | ff962a3 | 2008-03-02 09:21:38 +0100 | [diff] [blame] | 302 | `<flags>`:: |
| 303 | `<flags>` are of `*`, `=`, `?` or `!`. |
| 304 | * Use `=` if the option takes an argument. |
| 305 | |
Nicolas Vigier | f8c8721 | 2013-10-31 12:08:29 +0100 | [diff] [blame] | 306 | * Use `?` to mean that the option takes an optional argument. You |
| 307 | probably want to use the `--stuck-long` mode to be able to |
| 308 | unambiguously parse the optional argument. |
Pierre Habouzit | ff962a3 | 2008-03-02 09:21:38 +0100 | [diff] [blame] | 309 | |
| 310 | * Use `*` to mean that this option should not be listed in the usage |
| 311 | generated for the `-h` argument. It's shown for `--help-all` as |
Christian Couder | a5af0e2 | 2008-05-02 05:30:47 +0200 | [diff] [blame] | 312 | documented in linkgit:gitcli[7]. |
Pierre Habouzit | ff962a3 | 2008-03-02 09:21:38 +0100 | [diff] [blame] | 313 | |
| 314 | * Use `!` to not make the corresponding negated long option available. |
Pierre Habouzit | 21d4783 | 2007-11-04 11:30:53 +0100 | [diff] [blame] | 315 | |
| 316 | The remainder of the line, after stripping the spaces, is used |
| 317 | as the help associated to the option. |
| 318 | |
| 319 | Blank lines are ignored, and lines that don't match this specification are used |
| 320 | as option group headers (start the line with a space to create such |
| 321 | lines on purpose). |
| 322 | |
| 323 | Example |
| 324 | ~~~~~~~ |
| 325 | |
| 326 | ------------ |
| 327 | OPTS_SPEC="\ |
| 328 | some-command [options] <args>... |
| 329 | |
| 330 | some-command does foo and bar! |
| 331 | -- |
| 332 | h,help show the help |
| 333 | |
| 334 | foo some nifty option --foo |
| 335 | bar= some cool option --bar with an argument |
| 336 | |
| 337 | An option group Header |
| 338 | C? option C with an optional argument" |
| 339 | |
Thomas Rast | ac2e1e6 | 2010-07-30 17:01:50 +0200 | [diff] [blame] | 340 | eval "$(echo "$OPTS_SPEC" | git rev-parse --parseopt -- "$@" || echo exit $?)" |
Pierre Habouzit | 21d4783 | 2007-11-04 11:30:53 +0100 | [diff] [blame] | 341 | ------------ |
| 342 | |
Christian Couder | 5032537 | 2009-04-25 06:55:26 +0200 | [diff] [blame] | 343 | SQ-QUOTE |
| 344 | -------- |
| 345 | |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 346 | In `--sq-quote` mode, 'git rev-parse' echoes on the standard output a |
Christian Couder | 5032537 | 2009-04-25 06:55:26 +0200 | [diff] [blame] | 347 | single line suitable for `sh(1)` `eval`. This line is made by |
| 348 | normalizing the arguments following `--sq-quote`. Nothing other than |
| 349 | quoting the arguments is done. |
| 350 | |
| 351 | If you want command input to still be interpreted as usual by |
Thomas Rast | 0b444cd | 2010-01-10 00:33:00 +0100 | [diff] [blame] | 352 | 'git rev-parse' before the output is shell quoted, see the `--sq` |
Christian Couder | 5032537 | 2009-04-25 06:55:26 +0200 | [diff] [blame] | 353 | option. |
| 354 | |
| 355 | Example |
| 356 | ~~~~~~~ |
| 357 | |
| 358 | ------------ |
| 359 | $ cat >your-git-script.sh <<\EOF |
| 360 | #!/bin/sh |
| 361 | args=$(git rev-parse --sq-quote "$@") # quote user-supplied arguments |
| 362 | command="git frotz -n24 $args" # and use it inside a handcrafted |
| 363 | # command line |
| 364 | eval "$command" |
| 365 | EOF |
| 366 | |
| 367 | $ sh your-git-script.sh "a b'c" |
| 368 | ------------ |
| 369 | |
Christian Couder | 824b5dc | 2008-05-13 06:51:41 +0200 | [diff] [blame] | 370 | EXAMPLES |
| 371 | -------- |
| 372 | |
| 373 | * Print the object name of the current commit: |
| 374 | + |
| 375 | ------------ |
| 376 | $ git rev-parse --verify HEAD |
| 377 | ------------ |
| 378 | |
| 379 | * Print the commit object name from the revision in the $REV shell variable: |
| 380 | + |
| 381 | ------------ |
Michael Haggerty | 2db6067 | 2013-03-30 07:44:25 +0100 | [diff] [blame] | 382 | $ git rev-parse --verify $REV^{commit} |
Christian Couder | 824b5dc | 2008-05-13 06:51:41 +0200 | [diff] [blame] | 383 | ------------ |
| 384 | + |
| 385 | This will error out if $REV is empty or not a valid revision. |
| 386 | |
Michael Haggerty | 2db6067 | 2013-03-30 07:44:25 +0100 | [diff] [blame] | 387 | * Similar to above: |
Christian Couder | 824b5dc | 2008-05-13 06:51:41 +0200 | [diff] [blame] | 388 | + |
| 389 | ------------ |
| 390 | $ git rev-parse --default master --verify $REV |
| 391 | ------------ |
| 392 | + |
| 393 | but if $REV is empty, the commit object name from master will be printed. |
| 394 | |
Junio C Hamano | 7fc9d69 | 2005-08-23 01:49:47 -0700 | [diff] [blame] | 395 | GIT |
| 396 | --- |
Christian Couder | 9e1f0a8 | 2008-06-06 09:07:32 +0200 | [diff] [blame] | 397 | Part of the linkgit:git[1] suite |