OSDN Git Service

Add Git official document to help
[tortoisegit/TortoiseGitJp.git] / doc / source / en / TortoiseGit / git_doc / git-rev-parse.html.xml
1 <?xml version="1.0" encoding="UTF-8"?>\r
2 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">\r
3 \r
4 <article lang="en" id="git-rev-parse(1)">\r
5 <articleinfo>\r
6     <title>git-rev-parse(1)</title>\r
7         <indexterm>\r
8                 <primary>git-rev-parse(1)</primary>\r
9         </indexterm>\r
10 </articleinfo>\r
11 <simplesect id="_name">\r
12 <title>NAME</title>\r
13 <simpara>git-rev-parse - Pick out and massage parameters</simpara>\r
14 </simplesect>\r
15 <simplesect id="_synopsis">\r
16 <title>SYNOPSIS</title>\r
17 <simpara><emphasis>git rev-parse</emphasis> [ --option ] &lt;args&gt;&#8230;</simpara>\r
18 </simplesect>\r
19 <simplesect id="_description">\r
20 <title>DESCRIPTION</title>\r
21 <simpara>Many git porcelainish commands take mixture of flags\r
22 (i.e. parameters that begin with a dash <emphasis>-</emphasis>) and parameters\r
23 meant for the underlying <emphasis>git-rev-list</emphasis> command they use internally\r
24 and flags and parameters for the other commands they use\r
25 downstream of <emphasis>git-rev-list</emphasis>.  This command is used to\r
26 distinguish between them.</simpara>\r
27 </simplesect>\r
28 <simplesect id="_options">\r
29 <title>OPTIONS</title>\r
30 <variablelist>\r
31 <varlistentry>\r
32 <term>\r
33 --parseopt\r
34 </term>\r
35 <listitem>\r
36 <simpara>\r
37         Use <emphasis>git-rev-parse</emphasis> in option parsing mode (see PARSEOPT section below).\r
38 </simpara>\r
39 </listitem>\r
40 </varlistentry>\r
41 <varlistentry>\r
42 <term>\r
43 --keep-dash-dash\r
44 </term>\r
45 <listitem>\r
46 <simpara>\r
47         Only meaningful in <literal>--parseopt</literal> mode. Tells the option parser to echo\r
48         out the first <literal>--</literal> met instead of skipping it.\r
49 </simpara>\r
50 </listitem>\r
51 </varlistentry>\r
52 <varlistentry>\r
53 <term>\r
54 --revs-only\r
55 </term>\r
56 <listitem>\r
57 <simpara>\r
58         Do not output flags and parameters not meant for\r
59         <emphasis>git-rev-list</emphasis> command.\r
60 </simpara>\r
61 </listitem>\r
62 </varlistentry>\r
63 <varlistentry>\r
64 <term>\r
65 --no-revs\r
66 </term>\r
67 <listitem>\r
68 <simpara>\r
69         Do not output flags and parameters meant for\r
70         <emphasis>git-rev-list</emphasis> command.\r
71 </simpara>\r
72 </listitem>\r
73 </varlistentry>\r
74 <varlistentry>\r
75 <term>\r
76 --flags\r
77 </term>\r
78 <listitem>\r
79 <simpara>\r
80         Do not output non-flag parameters.\r
81 </simpara>\r
82 </listitem>\r
83 </varlistentry>\r
84 <varlistentry>\r
85 <term>\r
86 --no-flags\r
87 </term>\r
88 <listitem>\r
89 <simpara>\r
90         Do not output flag parameters.\r
91 </simpara>\r
92 </listitem>\r
93 </varlistentry>\r
94 <varlistentry>\r
95 <term>\r
96 --default &lt;arg&gt;\r
97 </term>\r
98 <listitem>\r
99 <simpara>\r
100         If there is no parameter given by the user, use <literal>&lt;arg&gt;</literal>\r
101         instead.\r
102 </simpara>\r
103 </listitem>\r
104 </varlistentry>\r
105 <varlistentry>\r
106 <term>\r
107 --verify\r
108 </term>\r
109 <listitem>\r
110 <simpara>\r
111         The parameter given must be usable as a single, valid\r
112         object name.  Otherwise barf and abort.\r
113 </simpara>\r
114 </listitem>\r
115 </varlistentry>\r
116 <varlistentry>\r
117 <term>\r
118 -q\r
119 </term>\r
120 <term>\r
121 --quiet\r
122 </term>\r
123 <listitem>\r
124 <simpara>\r
125         Only meaningful in <literal>--verify</literal> mode. Do not output an error\r
126         message if the first argument is not a valid object name;\r
127         instead exit with non-zero status silently.\r
128 </simpara>\r
129 </listitem>\r
130 </varlistentry>\r
131 <varlistentry>\r
132 <term>\r
133 --sq\r
134 </term>\r
135 <listitem>\r
136 <simpara>\r
137         Usually the output is made one line per flag and\r
138         parameter.  This option makes output a single line,\r
139         properly quoted for consumption by shell.  Useful when\r
140         you expect your parameter to contain whitespaces and\r
141         newlines (e.g. when using pickaxe <literal>-S</literal> with\r
142         <emphasis>git-diff-\*</emphasis>).\r
143 </simpara>\r
144 </listitem>\r
145 </varlistentry>\r
146 <varlistentry>\r
147 <term>\r
148 --not\r
149 </term>\r
150 <listitem>\r
151 <simpara>\r
152         When showing object names, prefix them with <emphasis>&#94;</emphasis> and\r
153         strip <emphasis>&#94;</emphasis> prefix from the object names that already have\r
154         one.\r
155 </simpara>\r
156 </listitem>\r
157 </varlistentry>\r
158 <varlistentry>\r
159 <term>\r
160 --symbolic\r
161 </term>\r
162 <listitem>\r
163 <simpara>\r
164         Usually the object names are output in SHA1 form (with\r
165         possible <emphasis>&#94;</emphasis> prefix); this option makes them output in a\r
166         form as close to the original input as possible.\r
167 </simpara>\r
168 </listitem>\r
169 </varlistentry>\r
170 <varlistentry>\r
171 <term>\r
172 --symbolic-full-name\r
173 </term>\r
174 <listitem>\r
175 <simpara>\r
176         This is similar to --symbolic, but it omits input that\r
177         are not refs (i.e. branch or tag names; or more\r
178         explicitly disambiguating "heads/master" form, when you\r
179         want to name the "master" branch when there is an\r
180         unfortunately named tag "master"), and show them as full\r
181         refnames (e.g. "refs/heads/master").\r
182 </simpara>\r
183 </listitem>\r
184 </varlistentry>\r
185 <varlistentry>\r
186 <term>\r
187 --all\r
188 </term>\r
189 <listitem>\r
190 <simpara>\r
191         Show all refs found in <literal>$GIT_DIR/refs</literal>.\r
192 </simpara>\r
193 </listitem>\r
194 </varlistentry>\r
195 <varlistentry>\r
196 <term>\r
197 --branches\r
198 </term>\r
199 <listitem>\r
200 <simpara>\r
201         Show branch refs found in <literal>$GIT_DIR/refs/heads</literal>.\r
202 </simpara>\r
203 </listitem>\r
204 </varlistentry>\r
205 <varlistentry>\r
206 <term>\r
207 --tags\r
208 </term>\r
209 <listitem>\r
210 <simpara>\r
211         Show tag refs found in <literal>$GIT_DIR/refs/tags</literal>.\r
212 </simpara>\r
213 </listitem>\r
214 </varlistentry>\r
215 <varlistentry>\r
216 <term>\r
217 --remotes\r
218 </term>\r
219 <listitem>\r
220 <simpara>\r
221         Show tag refs found in <literal>$GIT_DIR/refs/remotes</literal>.\r
222 </simpara>\r
223 </listitem>\r
224 </varlistentry>\r
225 <varlistentry>\r
226 <term>\r
227 --show-prefix\r
228 </term>\r
229 <listitem>\r
230 <simpara>\r
231         When the command is invoked from a subdirectory, show the\r
232         path of the current directory relative to the top-level\r
233         directory.\r
234 </simpara>\r
235 </listitem>\r
236 </varlistentry>\r
237 <varlistentry>\r
238 <term>\r
239 --show-cdup\r
240 </term>\r
241 <listitem>\r
242 <simpara>\r
243         When the command is invoked from a subdirectory, show the\r
244         path of the top-level directory relative to the current\r
245         directory (typically a sequence of "../", or an empty string).\r
246 </simpara>\r
247 </listitem>\r
248 </varlistentry>\r
249 <varlistentry>\r
250 <term>\r
251 --git-dir\r
252 </term>\r
253 <listitem>\r
254 <simpara>\r
255         Show <literal>$GIT_DIR</literal> if defined else show the path to the .git directory.\r
256 </simpara>\r
257 </listitem>\r
258 </varlistentry>\r
259 <varlistentry>\r
260 <term>\r
261 --is-inside-git-dir\r
262 </term>\r
263 <listitem>\r
264 <simpara>\r
265         When the current working directory is below the repository\r
266         directory print "true", otherwise "false".\r
267 </simpara>\r
268 </listitem>\r
269 </varlistentry>\r
270 <varlistentry>\r
271 <term>\r
272 --is-inside-work-tree\r
273 </term>\r
274 <listitem>\r
275 <simpara>\r
276         When the current working directory is inside the work tree of the\r
277         repository print "true", otherwise "false".\r
278 </simpara>\r
279 </listitem>\r
280 </varlistentry>\r
281 <varlistentry>\r
282 <term>\r
283 --is-bare-repository\r
284 </term>\r
285 <listitem>\r
286 <simpara>\r
287         When the repository is bare print "true", otherwise "false".\r
288 </simpara>\r
289 </listitem>\r
290 </varlistentry>\r
291 <varlistentry>\r
292 <term>\r
293 --short\r
294 </term>\r
295 <term>\r
296 --short=number\r
297 </term>\r
298 <listitem>\r
299 <simpara>\r
300         Instead of outputting the full SHA1 values of object names try to\r
301         abbreviate them to a shorter unique name. When no length is specified\r
302         7 is used. The minimum length is 4.\r
303 </simpara>\r
304 </listitem>\r
305 </varlistentry>\r
306 <varlistentry>\r
307 <term>\r
308 --since=datestring\r
309 </term>\r
310 <term>\r
311 --after=datestring\r
312 </term>\r
313 <listitem>\r
314 <simpara>\r
315         Parse the date string, and output the corresponding\r
316         --max-age= parameter for <emphasis>git-rev-list</emphasis>.\r
317 </simpara>\r
318 </listitem>\r
319 </varlistentry>\r
320 <varlistentry>\r
321 <term>\r
322 --until=datestring\r
323 </term>\r
324 <term>\r
325 --before=datestring\r
326 </term>\r
327 <listitem>\r
328 <simpara>\r
329         Parse the date string, and output the corresponding\r
330         --min-age= parameter for <emphasis>git-rev-list</emphasis>.\r
331 </simpara>\r
332 </listitem>\r
333 </varlistentry>\r
334 <varlistentry>\r
335 <term>\r
336 &lt;args&gt;&#8230;\r
337 </term>\r
338 <listitem>\r
339 <simpara>\r
340         Flags and parameters to be parsed.\r
341 </simpara>\r
342 </listitem>\r
343 </varlistentry>\r
344 </variablelist>\r
345 </simplesect>\r
346 <simplesect id="_specifying_revisions">\r
347 <title>SPECIFYING REVISIONS</title>\r
348 <simpara>A revision parameter typically, but not necessarily, names a\r
349 commit object.  They use what is called an <emphasis>extended SHA1</emphasis>\r
350 syntax.  Here are various ways to spell object names.  The\r
351 ones listed near the end of this list are to name trees and\r
352 blobs contained in a commit.</simpara>\r
353 <itemizedlist>\r
354 <listitem>\r
355 <simpara>\r
356 The full SHA1 object name (40-byte hexadecimal string), or\r
357   a substring of such that is unique within the repository.\r
358   E.g. dae86e1950b1277e545cee180551750029cfe735 and dae86e both\r
359   name the same commit object if there are no other object in\r
360   your repository whose object name starts with dae86e.\r
361 </simpara>\r
362 </listitem>\r
363 <listitem>\r
364 <simpara>\r
365 An output from <emphasis>git-describe</emphasis>; i.e. a closest tag, optionally\r
366   followed by a dash and a number of commits, followed by a dash, a\r
367   <literal>g</literal>, and an abbreviated object name.\r
368 </simpara>\r
369 </listitem>\r
370 <listitem>\r
371 <simpara>\r
372 A symbolic ref name.  E.g. <emphasis>master</emphasis> typically means the commit\r
373   object referenced by $GIT_DIR/refs/heads/master.  If you\r
374   happen to have both heads/master and tags/master, you can\r
375   explicitly say <emphasis>heads/master</emphasis> to tell git which one you mean.\r
376   When ambiguous, a <literal>&lt;name&gt;</literal> is disambiguated by taking the\r
377   first match in the following rules:\r
378 </simpara>\r
379 <orderedlist numeration="arabic">\r
380 <listitem>\r
381 <simpara>\r
382 if <literal>$GIT_DIR/&lt;name&gt;</literal> exists, that is what you mean (this is usually\r
383     useful only for <literal>HEAD</literal>, <literal>FETCH_HEAD</literal>, <literal>ORIG_HEAD</literal> and <literal>MERGE_HEAD</literal>);\r
384 </simpara>\r
385 </listitem>\r
386 <listitem>\r
387 <simpara>\r
388 otherwise, <literal>$GIT_DIR/refs/&lt;name&gt;</literal> if exists;\r
389 </simpara>\r
390 </listitem>\r
391 <listitem>\r
392 <simpara>\r
393 otherwise, <literal>$GIT_DIR/refs/tags/&lt;name&gt;</literal> if exists;\r
394 </simpara>\r
395 </listitem>\r
396 <listitem>\r
397 <simpara>\r
398 otherwise, <literal>$GIT_DIR/refs/heads/&lt;name&gt;</literal> if exists;\r
399 </simpara>\r
400 </listitem>\r
401 <listitem>\r
402 <simpara>\r
403 otherwise, <literal>$GIT_DIR/refs/remotes/&lt;name&gt;</literal> if exists;\r
404 </simpara>\r
405 </listitem>\r
406 <listitem>\r
407 <simpara>\r
408 otherwise, <literal>$GIT_DIR/refs/remotes/&lt;name&gt;/HEAD</literal> if exists.\r
409 </simpara>\r
410 <simpara>HEAD names the commit your changes in the working tree is based on.\r
411 FETCH_HEAD records the branch you fetched from a remote repository\r
412 with your last <emphasis>git-fetch</emphasis> invocation.\r
413 ORIG_HEAD is created by commands that moves your HEAD in a drastic\r
414 way, to record the position of the HEAD before their operation, so that\r
415 you can change the tip of the branch back to the state before you ran\r
416 them easily.\r
417 MERGE_HEAD records the commit(s) you are merging into your branch\r
418 when you run <emphasis>git-merge</emphasis>.</simpara>\r
419 </listitem>\r
420 </orderedlist>\r
421 </listitem>\r
422 <listitem>\r
423 <simpara>\r
424 A ref followed by the suffix <emphasis>@</emphasis> with a date specification\r
425   enclosed in a brace\r
426   pair (e.g. <emphasis>{yesterday}</emphasis>, <emphasis>{1 month 2 weeks 3 days 1 hour 1\r
427   second ago}</emphasis> or <emphasis>{1979-02-26 18:30:00}</emphasis>) to specify the value\r
428   of the ref at a prior point in time.  This suffix may only be\r
429   used immediately following a ref name and the ref must have an\r
430   existing log ($GIT_DIR/logs/&lt;ref&gt;). Note that this looks up the state\r
431   of your <emphasis role="strong">local</emphasis> ref at a given time; e.g., what was in your local\r
432   <literal>master</literal> branch last week. If you want to look at commits made during\r
433   certain times, see <literal>--since</literal> and <literal>--until</literal>.\r
434 </simpara>\r
435 </listitem>\r
436 <listitem>\r
437 <simpara>\r
438 A ref followed by the suffix <emphasis>@</emphasis> with an ordinal specification\r
439   enclosed in a brace pair (e.g. <emphasis>{1}</emphasis>, <emphasis>{15}</emphasis>) to specify\r
440   the n-th prior value of that ref.  For example <emphasis>master@{1}</emphasis>\r
441   is the immediate prior value of <emphasis>master</emphasis> while <emphasis>master@{5}</emphasis>\r
442   is the 5th prior value of <emphasis>master</emphasis>. This suffix may only be used\r
443   immediately following a ref name and the ref must have an existing\r
444   log ($GIT_DIR/logs/&lt;ref&gt;).\r
445 </simpara>\r
446 </listitem>\r
447 <listitem>\r
448 <simpara>\r
449 You can use the <emphasis>@</emphasis> construct with an empty ref part to get at a\r
450   reflog of the current branch. For example, if you are on the\r
451   branch <emphasis>blabla</emphasis>, then <emphasis>@{1}</emphasis> means the same as <emphasis>blabla@{1}</emphasis>.\r
452 </simpara>\r
453 </listitem>\r
454 <listitem>\r
455 <simpara>\r
456 The special construct <emphasis>@{-&lt;n&gt;}</emphasis> means the &lt;n&gt;th branch checked out\r
457   before the current one.\r
458 </simpara>\r
459 </listitem>\r
460 <listitem>\r
461 <simpara>\r
462 A suffix <emphasis>&#94;</emphasis> to a revision parameter means the first parent of\r
463   that commit object.  <emphasis>&#94;&lt;n&gt;</emphasis> means the &lt;n&gt;th parent (i.e.\r
464   <emphasis>rev&#94;</emphasis>\r
465   is equivalent to <emphasis>rev&#94;1</emphasis>).  As a special rule,\r
466   <emphasis>rev&#94;0</emphasis> means the commit itself and is used when <emphasis>rev</emphasis> is the\r
467   object name of a tag object that refers to a commit object.\r
468 </simpara>\r
469 </listitem>\r
470 <listitem>\r
471 <simpara>\r
472 A suffix <emphasis>&#126;&lt;n&gt;</emphasis> to a revision parameter means the commit\r
473   object that is the &lt;n&gt;th generation grand-parent of the named\r
474   commit object, following only the first parent.  I.e. rev~3 is\r
475   equivalent to rev&#94;&#94;&#94; which is equivalent to\r
476   rev&#94;1&#94;1&#94;1.  See below for a illustration of\r
477   the usage of this form.\r
478 </simpara>\r
479 </listitem>\r
480 <listitem>\r
481 <simpara>\r
482 A suffix <emphasis>&#94;</emphasis> followed by an object type name enclosed in\r
483   brace pair (e.g. <literal>v0.99.8&#94;{commit}</literal>) means the object\r
484   could be a tag, and dereference the tag recursively until an\r
485   object of that type is found or the object cannot be\r
486   dereferenced anymore (in which case, barf).  <literal>rev&#94;0</literal>\r
487   introduced earlier is a short-hand for <literal>rev&#94;{commit}</literal>.\r
488 </simpara>\r
489 </listitem>\r
490 <listitem>\r
491 <simpara>\r
492 A suffix <emphasis>&#94;</emphasis> followed by an empty brace pair\r
493   (e.g. <literal>v0.99.8&#94;{}</literal>) means the object could be a tag,\r
494   and dereference the tag recursively until a non-tag object is\r
495   found.\r
496 </simpara>\r
497 </listitem>\r
498 <listitem>\r
499 <simpara>\r
500 A colon, followed by a slash, followed by a text: this names\r
501   a commit whose commit message starts with the specified text.\r
502   This name returns the youngest matching commit which is\r
503   reachable from any ref.  If the commit message starts with a\r
504   <emphasis>!</emphasis>, you have to repeat that;  the special sequence <emphasis>:/!</emphasis>,\r
505   followed by something else than <emphasis>!</emphasis> is reserved for now.\r
506 </simpara>\r
507 </listitem>\r
508 <listitem>\r
509 <simpara>\r
510 A suffix <emphasis>:</emphasis> followed by a path; this names the blob or tree\r
511   at the given path in the tree-ish object named by the part\r
512   before the colon.\r
513 </simpara>\r
514 </listitem>\r
515 <listitem>\r
516 <simpara>\r
517 A colon, optionally followed by a stage number (0 to 3) and a\r
518   colon, followed by a path; this names a blob object in the\r
519   index at the given path.  Missing stage number (and the colon\r
520   that follows it) names a stage 0 entry. During a merge, stage\r
521   1 is the common ancestor, stage 2 is the target branch&#8217;s version\r
522   (typically the current branch), and stage 3 is the version from\r
523   the branch being merged.\r
524 </simpara>\r
525 </listitem>\r
526 </itemizedlist>\r
527 <simpara>Here is an illustration, by Jon Loeliger.  Both commit nodes B\r
528 and C are parents of commit node A.  Parent commits are ordered\r
529 left-to-right.</simpara>\r
530 <literallayout class="monospaced">G   H   I   J\r
531  \ /     \ /\r
532   D   E   F\r
533    \  |  / \\r
534     \ | /   |\r
535      \|/    |\r
536       B     C\r
537        \   /\r
538         \ /\r
539          A</literallayout>\r
540 <literallayout class="monospaced">A =      = A^0\r
541 B = A^   = A^1     = A~1\r
542 C = A^2  = A^2\r
543 D = A^^  = A^1^1   = A~2\r
544 E = B^2  = A^^2\r
545 F = B^3  = A^^3\r
546 G = A^^^ = A^1^1^1 = A~3\r
547 H = D^2  = B^^2    = A^^^2  = A~2^2\r
548 I = F^   = B^3^    = A^^3^\r
549 J = F^2  = B^3^2   = A^^3^2</literallayout>\r
550 </simplesect>\r
551 <simplesect id="_specifying_ranges">\r
552 <title>SPECIFYING RANGES</title>\r
553 <simpara>History traversing commands such as <emphasis>git-log</emphasis> operate on a set\r
554 of commits, not just a single commit.  To these commands,\r
555 specifying a single revision with the notation described in the\r
556 previous section means the set of commits reachable from that\r
557 commit, following the commit ancestry chain.</simpara>\r
558 <simpara>To exclude commits reachable from a commit, a prefix <literal>&#94;</literal>\r
559 notation is used.  E.g. "<literal>&#94;r1 r2</literal>" means commits reachable\r
560 from <literal>r2</literal> but exclude the ones reachable from <literal>r1</literal>.</simpara>\r
561 <simpara>This set operation appears so often that there is a shorthand\r
562 for it.  When you have two commits <literal>r1</literal> and <literal>r2</literal> (named according\r
563 to the syntax explained in SPECIFYING REVISIONS above), you can ask\r
564 for commits that are reachable from r2 excluding those that are reachable\r
565 from r1 by "<literal>&#94;r1 r2</literal>" and it can be written as "<literal>r1..r2</literal>".</simpara>\r
566 <simpara>A similar notation "<literal>r1...r2</literal>" is called symmetric difference\r
567 of <literal>r1</literal> and <literal>r2</literal> and is defined as\r
568 "<literal>r1 r2 --not $(git merge-base --all r1 r2)</literal>".\r
569 It is the set of commits that are reachable from either one of\r
570 <literal>r1</literal> or <literal>r2</literal> but not from both.</simpara>\r
571 <simpara>Two other shorthands for naming a set that is formed by a commit\r
572 and its parent commits exist.  The <literal>r1&#94;@</literal> notation means all\r
573 parents of <literal>r1</literal>.  <literal>r1&#94;!</literal> includes commit <literal>r1</literal> but excludes\r
574 all of its parents.</simpara>\r
575 <simpara>Here are a handful of examples:</simpara>\r
576 <literallayout class="monospaced">D                G H D\r
577 D F              G H I J D F\r
578 ^G D             H D\r
579 ^D B             E I J F B\r
580 B...C            G H D E B C\r
581 ^D B C           E I J F B C\r
582 C^@              I J F\r
583 F^! D            G H D F</literallayout>\r
584 </simplesect>\r
585 <simplesect id="_parseopt">\r
586 <title>PARSEOPT</title>\r
587 <simpara>In <literal>--parseopt</literal> mode, <emphasis>git-rev-parse</emphasis> helps massaging options to bring to shell\r
588 scripts the same facilities C builtins have. It works as an option normalizer\r
589 (e.g. splits single switches aggregate values), a bit like <literal>getopt(1)</literal> does.</simpara>\r
590 <simpara>It takes on the standard input the specification of the options to parse and\r
591 understand, and echoes on the standard output a line suitable for <literal>sh(1)</literal> <literal>eval</literal>\r
592 to replace the arguments with normalized ones.  In case of error, it outputs\r
593 usage on the standard error stream, and exits with code 129.</simpara>\r
594 <simplesect id="_input_format">\r
595 <title>Input Format</title>\r
596 <simpara><emphasis>git-rev-parse --parseopt</emphasis> input format is fully text based. It has two parts,\r
597 separated by a line that contains only <literal>--</literal>. The lines before the separator\r
598 (should be more than one) are used for the usage.\r
599 The lines after the separator describe the options.</simpara>\r
600 <simpara>Each line of options has this format:</simpara>\r
601 <literallayout>&lt;opt_spec&gt;&lt;flags&gt;* SP+ help LF</literallayout>\r
602 <variablelist>\r
603 <varlistentry>\r
604 <term>\r
605 <literal>&lt;opt_spec&gt;</literal>\r
606 </term>\r
607 <listitem>\r
608 <simpara>\r
609         its format is the short option character, then the long option name\r
610         separated by a comma. Both parts are not required, though at least one\r
611         is necessary. <literal>h,help</literal>, <literal>dry-run</literal> and <literal>f</literal> are all three correct\r
612         <literal>&lt;opt_spec&gt;</literal>.\r
613 </simpara>\r
614 </listitem>\r
615 </varlistentry>\r
616 <varlistentry>\r
617 <term>\r
618 <literal>&lt;flags&gt;</literal>\r
619 </term>\r
620 <listitem>\r
621 <simpara>\r
622         <literal>&lt;flags&gt;</literal> are of <literal>*</literal>, <literal>=</literal>, <literal>?</literal> or <literal>!</literal>.\r
623 </simpara>\r
624 <itemizedlist>\r
625 <listitem>\r
626 <simpara>\r
627 Use <literal>=</literal> if the option takes an argument.\r
628 </simpara>\r
629 </listitem>\r
630 <listitem>\r
631 <simpara>\r
632 Use <literal>?</literal> to mean that the option is optional (though its use is discouraged).\r
633 </simpara>\r
634 </listitem>\r
635 <listitem>\r
636 <simpara>\r
637 Use <literal>*</literal> to mean that this option should not be listed in the usage\r
638           generated for the <literal>-h</literal> argument. It&#8217;s shown for <literal>--help-all</literal> as\r
639           documented in <xref linkend="gitcli(7)"/>.\r
640 </simpara>\r
641 </listitem>\r
642 <listitem>\r
643 <simpara>\r
644 Use <literal>!</literal> to not make the corresponding negated long option available.\r
645 </simpara>\r
646 </listitem>\r
647 </itemizedlist>\r
648 </listitem>\r
649 </varlistentry>\r
650 </variablelist>\r
651 <simpara>The remainder of the line, after stripping the spaces, is used\r
652 as the help associated to the option.</simpara>\r
653 <simpara>Blank lines are ignored, and lines that don&#8217;t match this specification are used\r
654 as option group headers (start the line with a space to create such\r
655 lines on purpose).</simpara>\r
656 </simplesect>\r
657 <simplesect id="_example">\r
658 <title>Example</title>\r
659 <literallayout>OPTS_SPEC="\\r
660 some-command [options] &lt;args&gt;...\r
661 \r
662 some-command does foo and bar!\r
663 --\r
664 h,help    show the help\r
665 \r
666 foo       some nifty option --foo\r
667 bar=      some cool option --bar with an argument\r
668 \r
669   An option group Header\r
670 C?        option C with an optional argument"\r
671 \r
672 eval `echo "$OPTS_SPEC" | git rev-parse --parseopt -- "$@" || echo exit $?`</literallayout>\r
673 </simplesect>\r
674 </simplesect>\r
675 <simplesect id="_examples">\r
676 <title>EXAMPLES</title>\r
677 <itemizedlist>\r
678 <listitem>\r
679 <simpara>\r
680 Print the object name of the current commit:\r
681 </simpara>\r
682 <literallayout>$ git rev-parse --verify HEAD</literallayout>\r
683 </listitem>\r
684 <listitem>\r
685 <simpara>\r
686 Print the commit object name from the revision in the $REV shell variable:\r
687 </simpara>\r
688 <literallayout>$ git rev-parse --verify $REV</literallayout>\r
689 <simpara>This will error out if $REV is empty or not a valid revision.</simpara>\r
690 </listitem>\r
691 <listitem>\r
692 <simpara>\r
693 Same as above:\r
694 </simpara>\r
695 <literallayout>$ git rev-parse --default master --verify $REV</literallayout>\r
696 <simpara>but if $REV is empty, the commit object name from master will be printed.</simpara>\r
697 </listitem>\r
698 </itemizedlist>\r
699 </simplesect>\r
700 <simplesect id="_author">\r
701 <title>Author</title>\r
702 <simpara>Written by Linus Torvalds &lt;<ulink url="mailto:torvalds@osdl.org">torvalds@osdl.org</ulink>&gt; .\r
703 Junio C Hamano &lt;<ulink url="mailto:gitster@pobox.com">gitster@pobox.com</ulink>&gt; and Pierre Habouzit &lt;<ulink url="mailto:madcoder@debian.org">madcoder@debian.org</ulink>&gt;</simpara>\r
704 </simplesect>\r
705 <simplesect id="_documentation">\r
706 <title>Documentation</title>\r
707 <simpara>Documentation by Junio C Hamano and the git-list &lt;<ulink url="mailto:git@vger.kernel.org">git@vger.kernel.org</ulink>&gt;.</simpara>\r
708 </simplesect>\r
709 <simplesect id="_git">\r
710 <title>GIT</title>\r
711 <simpara>Part of the <xref linkend="git(1)"/> suite</simpara>\r
712 </simplesect>\r
713 </article>\r