Google Git
Sign in
chromium / external / gitster / git-htmldocs / 600334628294fbcd6406b55a9a17d270371cb7e5 / . / gitcli.html
blob: a25f73361e34bcb5b5e15e1fade6618dd28eb033 [file] [log] [blame]
Junio C Hamanof556fc22007-12-23 08:16:38[diff] [blame]1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
2 "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
3<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]6<meta name="generator" content="AsciiDoc 8.4.5" />
7<title>gitcli(7)</title>
Junio C Hamanof556fc22007-12-23 08:16:38[diff] [blame]8<style type="text/css">
9/* Debug borders */
10p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
11/*
12 border: 1px solid red;
13*/
14}
15
16body {
17 margin: 1em 5% 1em 5%;
18}
19
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]20a {
21 color: blue;
22 text-decoration: underline;
23}
24a:visited {
25 color: fuchsia;
26}
Junio C Hamanof556fc22007-12-23 08:16:38[diff] [blame]27
28em {
29 font-style: italic;
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]30 color: navy;
Junio C Hamanof556fc22007-12-23 08:16:38[diff] [blame]31}
32
33strong {
34 font-weight: bold;
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]35 color: #083194;
Junio C Hamanof556fc22007-12-23 08:16:38[diff] [blame]36}
37
38tt {
39 color: navy;
40}
41
42h1, h2, h3, h4, h5, h6 {
43 color: #527bbd;
44 font-family: sans-serif;
45 margin-top: 1.2em;
46 margin-bottom: 0.5em;
47 line-height: 1.3;
48}
49
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]50h1, h2, h3 {
Junio C Hamanof556fc22007-12-23 08:16:38[diff] [blame]51 border-bottom: 2px solid silver;
52}
53h2 {
Junio C Hamanof556fc22007-12-23 08:16:38[diff] [blame]54 padding-top: 0.5em;
55}
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]56h3 {
57 float: left;
58}
59h3 + * {
60 clear: left;
61}
Junio C Hamanof556fc22007-12-23 08:16:38[diff] [blame]62
63div.sectionbody {
64 font-family: serif;
65 margin-left: 0;
66}
67
68hr {
69 border: 1px solid silver;
70}
71
72p {
73 margin-top: 0.5em;
74 margin-bottom: 0.5em;
75}
76
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]77ul, ol, li > p {
78 margin-top: 0;
79}
80
Junio C Hamanof556fc22007-12-23 08:16:38[diff] [blame]81pre {
82 padding: 0;
83 margin: 0;
84}
85
86span#author {
87 color: #527bbd;
88 font-family: sans-serif;
89 font-weight: bold;
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]90 font-size: 1.1em;
Junio C Hamanof556fc22007-12-23 08:16:38[diff] [blame]91}
92span#email {
93}
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]94span#revnumber, span#revdate, span#revremark {
Junio C Hamanof556fc22007-12-23 08:16:38[diff] [blame]95 font-family: sans-serif;
96}
97
98div#footer {
99 font-family: sans-serif;
100 font-size: small;
101 border-top: 2px solid silver;
102 padding-top: 0.5em;
103 margin-top: 4.0em;
104}
105div#footer-text {
106 float: left;
107 padding-bottom: 0.5em;
108}
109div#footer-badges {
110 float: right;
111 padding-bottom: 0.5em;
112}
113
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]114div#preamble {
115 margin-top: 1.5em;
116 margin-bottom: 1.5em;
117}
Junio C Hamanof556fc22007-12-23 08:16:38[diff] [blame]118div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
119div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
120div.admonitionblock {
Junio C Hamanof556fc22007-12-23 08:16:38[diff] [blame]121 margin-top: 1.5em;
122 margin-bottom: 1.5em;
123}
124div.admonitionblock {
125 margin-top: 2.5em;
126 margin-bottom: 2.5em;
127}
128
129div.content { /* Block element content. */
130 padding: 0;
131}
132
133/* Block element titles. */
134div.title, caption.title {
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]135 color: #527bbd;
Junio C Hamanof556fc22007-12-23 08:16:38[diff] [blame]136 font-family: sans-serif;
137 font-weight: bold;
138 text-align: left;
139 margin-top: 1.0em;
140 margin-bottom: 0.5em;
141}
142div.title + * {
143 margin-top: 0;
144}
145
146td div.title:first-child {
147 margin-top: 0.0em;
148}
149div.content div.title:first-child {
150 margin-top: 0.0em;
151}
152div.content + div.title {
153 margin-top: 0.0em;
154}
155
156div.sidebarblock > div.content {
157 background: #ffffee;
158 border: 1px solid silver;
159 padding: 0.5em;
160}
161
162div.listingblock > div.content {
163 border: 1px solid silver;
164 background: #f4f4f4;
165 padding: 0.5em;
166}
167
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]168div.quoteblock {
Junio C Hamanof556fc22007-12-23 08:16:38[diff] [blame]169 padding-left: 2.0em;
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]170 margin-right: 10%;
Junio C Hamanof556fc22007-12-23 08:16:38[diff] [blame]171}
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]172div.quoteblock > div.attribution {
173 padding-top: 0.5em;
Junio C Hamanof556fc22007-12-23 08:16:38[diff] [blame]174 text-align: right;
175}
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]176
177div.verseblock {
178 padding-left: 2.0em;
179 margin-right: 10%;
180}
181div.verseblock > div.content {
182 white-space: pre;
183}
184div.verseblock > div.attribution {
185 padding-top: 0.75em;
186 text-align: left;
187}
188/* DEPRECATED: Pre version 8.2.7 verse style literal block. */
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]189div.verseblock + div.attribution {
190 text-align: left;
191}
Junio C Hamanof556fc22007-12-23 08:16:38[diff] [blame]192
193div.admonitionblock .icon {
194 vertical-align: top;
195 font-size: 1.1em;
196 font-weight: bold;
197 text-decoration: underline;
198 color: #527bbd;
199 padding-right: 0.5em;
200}
201div.admonitionblock td.content {
202 padding-left: 0.5em;
203 border-left: 2px solid silver;
204}
205
206div.exampleblock > div.content {
207 border-left: 2px solid silver;
208 padding: 0.5em;
209}
210
Junio C Hamanof556fc22007-12-23 08:16:38[diff] [blame]211div.imageblock div.content { padding-left: 0; }
Junio C Hamanof556fc22007-12-23 08:16:38[diff] [blame]212span.image img { border-style: none; }
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]213a.image:visited { color: white; }
Junio C Hamanof556fc22007-12-23 08:16:38[diff] [blame]214
215dl {
216 margin-top: 0.8em;
217 margin-bottom: 0.8em;
218}
219dt {
220 margin-top: 0.5em;
221 margin-bottom: 0;
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]222 font-style: normal;
223 color: navy;
Junio C Hamanof556fc22007-12-23 08:16:38[diff] [blame]224}
225dd > *:first-child {
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]226 margin-top: 0.1em;
Junio C Hamanof556fc22007-12-23 08:16:38[diff] [blame]227}
228
229ul, ol {
230 list-style-position: outside;
231}
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]232ol.arabic {
233 list-style-type: decimal;
234}
235ol.loweralpha {
Junio C Hamanof556fc22007-12-23 08:16:38[diff] [blame]236 list-style-type: lower-alpha;
237}
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]238ol.upperalpha {
239 list-style-type: upper-alpha;
240}
241ol.lowerroman {
242 list-style-type: lower-roman;
243}
244ol.upperroman {
245 list-style-type: upper-roman;
246}
247
248div.compact ul, div.compact ol,
249div.compact p, div.compact p,
250div.compact div, div.compact div {
251 margin-top: 0.1em;
252 margin-bottom: 0.1em;
253}
Junio C Hamanof556fc22007-12-23 08:16:38[diff] [blame]254
255div.tableblock > table {
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]256 border: 3px solid #527bbd;
Junio C Hamanof556fc22007-12-23 08:16:38[diff] [blame]257}
258thead {
259 font-family: sans-serif;
260 font-weight: bold;
261}
262tfoot {
263 font-weight: bold;
264}
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]265td > div.verse {
266 white-space: pre;
267}
268p.table {
269 margin-top: 0;
270}
271/* Because the table frame attribute is overriden by CSS in most browsers. */
272div.tableblock > table[frame="void"] {
273 border-style: none;
274}
275div.tableblock > table[frame="hsides"] {
276 border-left-style: none;
277 border-right-style: none;
278}
279div.tableblock > table[frame="vsides"] {
280 border-top-style: none;
281 border-bottom-style: none;
282}
Junio C Hamanof556fc22007-12-23 08:16:38[diff] [blame]283
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]284
285div.hdlist {
Junio C Hamanof556fc22007-12-23 08:16:38[diff] [blame]286 margin-top: 0.8em;
287 margin-bottom: 0.8em;
288}
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]289div.hdlist tr {
290 padding-bottom: 15px;
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]291}
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]292dt.hdlist1.strong, td.hdlist1.strong {
293 font-weight: bold;
294}
295td.hdlist1 {
Junio C Hamanof556fc22007-12-23 08:16:38[diff] [blame]296 vertical-align: top;
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]297 font-style: normal;
Junio C Hamanof556fc22007-12-23 08:16:38[diff] [blame]298 padding-right: 0.8em;
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]299 color: navy;
Junio C Hamanof556fc22007-12-23 08:16:38[diff] [blame]300}
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]301td.hdlist2 {
Junio C Hamanof556fc22007-12-23 08:16:38[diff] [blame]302 vertical-align: top;
303}
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]304div.hdlist.compact tr {
305 margin: 0;
306 padding-bottom: 0;
307}
308
309.comment {
310 background: yellow;
311}
Junio C Hamanof556fc22007-12-23 08:16:38[diff] [blame]312
313@media print {
314 div#footer-badges { display: none; }
315}
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]316
317div#toctitle {
318 color: #527bbd;
319 font-family: sans-serif;
320 font-size: 1.1em;
321 font-weight: bold;
322 margin-top: 1.0em;
323 margin-bottom: 0.1em;
324}
325
326div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
327 margin-top: 0;
328 margin-bottom: 0;
329}
330div.toclevel2 {
331 margin-left: 2em;
332 font-size: 0.9em;
333}
334div.toclevel3 {
335 margin-left: 4em;
336 font-size: 0.9em;
337}
338div.toclevel4 {
339 margin-left: 6em;
340 font-size: 0.9em;
341}
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]342/* Overrides for manpage documents */
343h1 {
344 padding-top: 0.5em;
345 padding-bottom: 0.5em;
346 border-top: 2px solid silver;
347 border-bottom: 2px solid silver;
348}
349h2 {
350 border-style: none;
351}
352div.sectionbody {
353 margin-left: 5%;
354}
355
356@media print {
357 div#toc { display: none; }
358}
359
Junio C Hamanof556fc22007-12-23 08:16:38[diff] [blame]360/* Workarounds for IE6's broken and incomplete CSS2. */
361
362div.sidebar-content {
363 background: #ffffee;
364 border: 1px solid silver;
365 padding: 0.5em;
366}
367div.sidebar-title, div.image-title {
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]368 color: #527bbd;
Junio C Hamanof556fc22007-12-23 08:16:38[diff] [blame]369 font-family: sans-serif;
370 font-weight: bold;
371 margin-top: 0.0em;
372 margin-bottom: 0.5em;
373}
374
375div.listingblock div.content {
376 border: 1px solid silver;
377 background: #f4f4f4;
378 padding: 0.5em;
379}
380
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]381div.quoteblock-attribution {
382 padding-top: 0.5em;
383 text-align: right;
384}
385
386div.verseblock-content {
387 white-space: pre;
388}
389div.verseblock-attribution {
390 padding-top: 0.75em;
391 text-align: left;
Junio C Hamanof556fc22007-12-23 08:16:38[diff] [blame]392}
393
394div.exampleblock-content {
395 border-left: 2px solid silver;
396 padding-left: 0.5em;
397}
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]398
399/* IE6 sets dynamically generated links as visited. */
400div#toc a:visited { color: blue; }
Junio C Hamanof556fc22007-12-23 08:16:38[diff] [blame]401</style>
Junio C Hamanof556fc22007-12-23 08:16:38[diff] [blame]402</head>
403<body>
404<div id="header">
405<h1>
Junio C Hamano2fbcd212008-05-14 22:26:07[diff] [blame]406gitcli(7) Manual Page
Junio C Hamanof556fc22007-12-23 08:16:38[diff] [blame]407</h1>
408<h2>NAME</h2>
409<div class="sectionbody">
410<p>gitcli -
411 git command line interface and conventions
412</p>
413</div>
414</div>
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]415<h2 id="_synopsis">SYNOPSIS</h2>
Junio C Hamanof556fc22007-12-23 08:16:38[diff] [blame]416<div class="sectionbody">
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]417<div class="paragraph"><p>gitcli</p></div>
Junio C Hamanof556fc22007-12-23 08:16:38[diff] [blame]418</div>
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]419<h2 id="_description">DESCRIPTION</h2>
Junio C Hamanof556fc22007-12-23 08:16:38[diff] [blame]420<div class="sectionbody">
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]421<div class="paragraph"><p>This manual describes the convention used throughout git CLI.</p></div>
422<div class="paragraph"><p>Many commands take revisions (most often "commits", but sometimes
Junio C Hamanoc4fec202008-06-28 10:07:24[diff] [blame]423"tree-ish", depending on the context and command) and paths as their
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]424arguments. Here are the rules:</p></div>
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]425<div class="ulist"><ul>
Junio C Hamanoc4fec202008-06-28 10:07:24[diff] [blame]426<li>
427<p>
428Revisions come first and then paths.
429 E.g. in <tt>git diff v1.0 v2.0 arch/x86 include/asm-x86</tt>,
430 <tt>v1.0</tt> and <tt>v2.0</tt> are revisions and <tt>arch/x86</tt> and <tt>include/asm-x86</tt>
431 are paths.
432</p>
433</li>
434<li>
435<p>
436When an argument can be misunderstood as either a revision or a path,
437 they can be disambiguated by placing <tt>--</tt> between them.
438 E.g. <tt>git diff -- HEAD</tt> is, "I have a file called HEAD in my work
439 tree. Please show changes between the version I staged in the index
440 and what I have in the work tree for that file". not "show difference
441 between the HEAD commit and the work tree as a whole". You can say
442 <tt>git diff HEAD --</tt> to ask for the latter.
443</p>
444</li>
445<li>
446<p>
447Without disambiguating <tt>--</tt>, git makes a reasonable guess, but errors
448 out and asking you to disambiguate when ambiguous. E.g. if you have a
449 file called HEAD in your work tree, <tt>git diff HEAD</tt> is ambiguous, and
450 you have to say either <tt>git diff HEAD --</tt> or <tt>git diff -- HEAD</tt> to
451 disambiguate.
452</p>
453</li>
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]454</ul></div>
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]455<div class="paragraph"><p>When writing a script that is expected to handle random user-input, it is
Junio C Hamanoc4fec202008-06-28 10:07:24[diff] [blame]456a good practice to make it explicit which arguments are which by placing
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]457disambiguating <tt>--</tt> at appropriate places.</p></div>
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]458<div class="paragraph"><p>Here are the rules regarding the "flags" that you should follow when you are
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]459scripting git:</p></div>
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]460<div class="ulist"><ul>
Junio C Hamanof556fc22007-12-23 08:16:38[diff] [blame]461<li>
462<p>
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]463it&#8217;s preferred to use the non dashed form of git commands, which means that
Junio C Hamanoea82cff2009-03-18 01:54:48[diff] [blame]464 you should prefer <tt>git foo</tt> to <tt>git-foo</tt>.
Junio C Hamanof556fc22007-12-23 08:16:38[diff] [blame]465</p>
466</li>
467<li>
468<p>
Junio C Hamanoea82cff2009-03-18 01:54:48[diff] [blame]469splitting short options to separate words (prefer <tt>git foo -a -b</tt>
470 to <tt>git foo -ab</tt>, the latter may not even work).
Junio C Hamanof556fc22007-12-23 08:16:38[diff] [blame]471</p>
472</li>
473<li>
474<p>
475when a command line option takes an argument, use the <em>sticked</em> form. In
Junio C Hamanoea82cff2009-03-18 01:54:48[diff] [blame]476 other words, write <tt>git foo -oArg</tt> instead of <tt>git foo -o Arg</tt> for short
477 options, and <tt>git foo --long-opt=Arg</tt> instead of <tt>git foo --long-opt Arg</tt>
Junio C Hamanof556fc22007-12-23 08:16:38[diff] [blame]478 for long options. An option that takes optional option-argument must be
479 written in the <em>sticked</em> form.
480</p>
481</li>
482<li>
483<p>
484when you give a revision parameter to a command, make sure the parameter is
485 not ambiguous with a name of a file in the work tree. E.g. do not write
Junio C Hamanoea82cff2009-03-18 01:54:48[diff] [blame]486 <tt>git log -1 HEAD</tt> but write <tt>git log -1 HEAD --</tt>; the former will not work
Junio C Hamanof556fc22007-12-23 08:16:38[diff] [blame]487 if you happen to have a file called <tt>HEAD</tt> in the work tree.
488</p>
489</li>
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]490</ul></div>
Junio C Hamanof556fc22007-12-23 08:16:38[diff] [blame]491</div>
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]492<h2 id="_enhanced_option_parser">ENHANCED OPTION PARSER</h2>
Junio C Hamanof556fc22007-12-23 08:16:38[diff] [blame]493<div class="sectionbody">
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]494<div class="paragraph"><p>From the git 1.5.4 series and further, many git commands (not all of them at the
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]495time of the writing though) come with an enhanced option parser.</p></div>
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]496<div class="paragraph"><p>Here is an exhaustive list of the facilities provided by this option parser.</p></div>
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]497<h3 id="_magic_options">Magic Options</h3><div style="clear:left"></div>
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]498<div class="paragraph"><p>Commands which have the enhanced option parser activated all understand a
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]499couple of magic command line options:</p></div>
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]500<div class="dlist"><dl>
501<dt class="hdlist1">
Junio C Hamanof556fc22007-12-23 08:16:38[diff] [blame]502-h
503</dt>
504<dd>
505<p>
506 gives a pretty printed usage of the command.
507</p>
508<div class="listingblock">
509<div class="content">
510<pre><tt>$ git describe -h
Junio C Hamanoe74124b2009-09-23 06:51:01[diff] [blame]511usage: git describe [options] &lt;committish&gt;*
Junio C Hamanof556fc22007-12-23 08:16:38[diff] [blame]512
513 --contains find the tag that comes after the commit
514 --debug debug search strategy on stderr
515 --all use any ref in .git/refs
516 --tags use any tag in .git/refs/tags
517 --abbrev [&lt;n&gt;] use &lt;n&gt; digits to display SHA-1s
518 --candidates &lt;n&gt; consider &lt;n&gt; most recent tags (default: 10)</tt></pre>
519</div></div>
520</dd>
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]521<dt class="hdlist1">
Junio C Hamanof556fc22007-12-23 08:16:38[diff] [blame]522--help-all
523</dt>
524<dd>
525<p>
526 Some git commands take options that are only used for plumbing or that
527 are deprecated, and such options are hidden from the default usage. This
528 option gives the full list of options.
529</p>
530</dd>
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]531</dl></div>
532<h3 id="_negating_options">Negating options</h3><div style="clear:left"></div>
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]533<div class="paragraph"><p>Options with long option names can be negated by prefixing <tt>--no-</tt>. For
Junio C Hamanoea82cff2009-03-18 01:54:48[diff] [blame]534example, <tt>git branch</tt> has the option <tt>--track</tt> which is <em>on</em> by default. You
535can use <tt>--no-track</tt> to override that behaviour. The same goes for <tt>--color</tt>
536and <tt>--no-color</tt>.</p></div>
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]537<h3 id="_aggregating_short_options">Aggregating short options</h3><div style="clear:left"></div>
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]538<div class="paragraph"><p>Commands that support the enhanced option parser allow you to aggregate short
Junio C Hamanoea82cff2009-03-18 01:54:48[diff] [blame]539options. This means that you can for example use <tt>git rm -rf</tt> or
540<tt>git clean -fdx</tt>.</p></div>
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]541<h3 id="_separating_argument_from_the_option">Separating argument from the option</h3><div style="clear:left"></div>
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]542<div class="paragraph"><p>You can write the mandatory option parameter to an option as a separate
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]543word on the command line. That means that all the following uses work:</p></div>
Junio C Hamanof556fc22007-12-23 08:16:38[diff] [blame]544<div class="listingblock">
545<div class="content">
546<pre><tt>$ git foo --long-opt=Arg
547$ git foo --long-opt Arg
548$ git foo -oArg
549$ git foo -o Arg</tt></pre>
550</div></div>
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]551<div class="paragraph"><p>However, this is <strong>NOT</strong> allowed for switches with an optional value, where the
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]552<em>sticked</em> form must be used:</p></div>
Junio C Hamanof556fc22007-12-23 08:16:38[diff] [blame]553<div class="listingblock">
554<div class="content">
555<pre><tt>$ git describe --abbrev HEAD # correct
556$ git describe --abbrev=10 HEAD # correct
557$ git describe --abbrev 10 HEAD # NOT WHAT YOU MEANT</tt></pre>
558</div></div>
559</div>
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]560<h2 id="_notes_on_frequently_confused_options">NOTES ON FREQUENTLY CONFUSED OPTIONS</h2>
Junio C Hamanofce7c7e2008-07-02 03:06:38[diff] [blame]561<div class="sectionbody">
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]562<div class="paragraph"><p>Many commands that can work on files in the working tree
Junio C Hamanofce7c7e2008-07-02 03:06:38[diff] [blame]563and/or in the index can take <tt>--cached</tt> and/or <tt>--index</tt>
564options. Sometimes people incorrectly think that, because
565the index was originally called cache, these two are
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]566synonyms. They are <strong>not</strong>&#8201;&#8212;&#8201;these two options mean very
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]567different things.</p></div>
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]568<div class="ulist"><ul>
Junio C Hamanofce7c7e2008-07-02 03:06:38[diff] [blame]569<li>
570<p>
571The <tt>--cached</tt> option is used to ask a command that
572 usually works on files in the working tree to <strong>only</strong> work
573 with the index. For example, <tt>git grep</tt>, when used
574 without a commit to specify from which commit to look for
575 strings in, usually works on files in the working tree,
576 but with the <tt>--cached</tt> option, it looks for strings in
577 the index.
578</p>
579</li>
580<li>
581<p>
582The <tt>--index</tt> option is used to ask a command that
583 usually works on files in the working tree to <strong>also</strong>
584 affect the index. For example, <tt>git stash apply</tt> usually
585 merges changes recorded in a stash to the working tree,
586 but with the <tt>--index</tt> option, it also merges changes to
587 the index as well.
588</p>
589</li>
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]590</ul></div>
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]591<div class="paragraph"><p><tt>git apply</tt> command can be used with <tt>--cached</tt> and
Junio C Hamanofce7c7e2008-07-02 03:06:38[diff] [blame]592<tt>--index</tt> (but not at the same time). Usually the command
593only affects the files in the working tree, but with
594<tt>--index</tt>, it patches both the files and their index
595entries, and with <tt>--cached</tt>, it modifies only the index
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]596entries.</p></div>
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]597<div class="paragraph"><p>See also <a href="http://marc.info/?l=git&amp;m=116563135620359">http://marc.info/?l=git&amp;m=116563135620359</a> and
598<a href="http://marc.info/?l=git&amp;m=119150393620273">http://marc.info/?l=git&amp;m=119150393620273</a> for further
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]599information.</p></div>
Junio C Hamanofce7c7e2008-07-02 03:06:38[diff] [blame]600</div>
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]601<h2 id="_git">GIT</h2>
Junio C Hamanof556fc22007-12-23 08:16:38[diff] [blame]602<div class="sectionbody">
Junio C Hamano103b5722011-01-31 05:03:45[diff] [blame]603<div class="paragraph"><p>Part of the <a href="git.html">git(1)</a> suite</p></div>
Junio C Hamanof556fc22007-12-23 08:16:38[diff] [blame]604</div>
605<div id="footer">
606<div id="footer-text">
Junio C Hamano5f3d8392011-03-15 23:33:35[diff] [blame]607Last updated 2011-03-15 23:30:15 UTC
Junio C Hamanof556fc22007-12-23 08:16:38[diff] [blame]608</div>
609</div>
610</body>
611</html>