Google Git
Sign in
chromium / external / gitster / git-htmldocs / ca8e07cd1946b3cef21a33dedcd5794a1e119cc0 / . / gitcli.html
blob: 9aed41a323b86dbfc599b1dc04d34598b1b1b869 [file] [log] [blame]
Junio C Hamanob96f40a2024-08-01 00:57:25[diff] [blame]1<!DOCTYPE html>
2<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
3<head>
4<meta charset="UTF-8"/>
5<meta http-equiv="X-UA-Compatible" content="IE=edge"/>
6<meta name="viewport" content="width=device-width, initial-scale=1.0"/>
Junio C Hamanod6a33e42025-02-18 23:45:11[diff] [blame]7<meta name="generator" content="Asciidoctor 2.0.23"/>
Junio C Hamanob96f40a2024-08-01 00:57:25[diff] [blame]8<title>gitcli(7)</title>
9<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700"/>
10<style>
11/*! Asciidoctor default stylesheet | MIT License | https://asciidoctor.org */
12/* Uncomment the following line when using as a custom stylesheet */
13/* @import "https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700"; */
14html{font-family:sans-serif;-webkit-text-size-adjust:100%}
15a{background:none}
16a:focus{outline:thin dotted}
17a:active,a:hover{outline:0}
18h1{font-size:2em;margin:.67em 0}
19b,strong{font-weight:bold}
20abbr{font-size:.9em}
21abbr[title]{cursor:help;border-bottom:1px dotted #dddddf;text-decoration:none}
22dfn{font-style:italic}
23hr{height:0}
24mark{background:#ff0;color:#000}
25code,kbd,pre,samp{font-family:monospace;font-size:1em}
26pre{white-space:pre-wrap}
27q{quotes:"\201C" "\201D" "\2018" "\2019"}
28small{font-size:80%}
29sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}
30sup{top:-.5em}
31sub{bottom:-.25em}
32img{border:0}
33svg:not(:root){overflow:hidden}
34figure{margin:0}
35audio,video{display:inline-block}
36audio:not([controls]){display:none;height:0}
37fieldset{border:1px solid silver;margin:0 2px;padding:.35em .625em .75em}
38legend{border:0;padding:0}
39button,input,select,textarea{font-family:inherit;font-size:100%;margin:0}
40button,input{line-height:normal}
41button,select{text-transform:none}
42button,html input[type=button],input[type=reset],input[type=submit]{-webkit-appearance:button;cursor:pointer}
43button[disabled],html input[disabled]{cursor:default}
44input[type=checkbox],input[type=radio]{padding:0}
45button::-moz-focus-inner,input::-moz-focus-inner{border:0;padding:0}
46textarea{overflow:auto;vertical-align:top}
47table{border-collapse:collapse;border-spacing:0}
48*,::before,::after{box-sizing:border-box}
49html,body{font-size:100%}
50body{background:#fff;color:rgba(0,0,0,.8);padding:0;margin:0;font-family:"Noto Serif","DejaVu Serif",serif;line-height:1;position:relative;cursor:auto;-moz-tab-size:4;-o-tab-size:4;tab-size:4;word-wrap:anywhere;-moz-osx-font-smoothing:grayscale;-webkit-font-smoothing:antialiased}
51a:hover{cursor:pointer}
52img,object,embed{max-width:100%;height:auto}
53object,embed{height:100%}
54img{-ms-interpolation-mode:bicubic}
55.left{float:left!important}
56.right{float:right!important}
57.text-left{text-align:left!important}
58.text-right{text-align:right!important}
59.text-center{text-align:center!important}
60.text-justify{text-align:justify!important}
61.hide{display:none}
62img,object,svg{display:inline-block;vertical-align:middle}
63textarea{height:auto;min-height:50px}
64select{width:100%}
65.subheader,.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{line-height:1.45;color:#7a2518;font-weight:400;margin-top:0;margin-bottom:.25em}
66div,dl,dt,dd,ul,ol,li,h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6,pre,form,p,blockquote,th,td{margin:0;padding:0}
67a{color:#2156a5;text-decoration:underline;line-height:inherit}
68a:hover,a:focus{color:#1d4b8f}
69a img{border:0}
70p{line-height:1.6;margin-bottom:1.25em;text-rendering:optimizeLegibility}
71p aside{font-size:.875em;line-height:1.35;font-style:italic}
72h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{font-family:"Open Sans","DejaVu Sans",sans-serif;font-weight:300;font-style:normal;color:#ba3925;text-rendering:optimizeLegibility;margin-top:1em;margin-bottom:.5em;line-height:1.0125em}
73h1 small,h2 small,h3 small,#toctitle small,.sidebarblock>.content>.title small,h4 small,h5 small,h6 small{font-size:60%;color:#e99b8f;line-height:0}
74h1{font-size:2.125em}
75h2{font-size:1.6875em}
76h3,#toctitle,.sidebarblock>.content>.title{font-size:1.375em}
77h4,h5{font-size:1.125em}
78h6{font-size:1em}
79hr{border:solid #dddddf;border-width:1px 0 0;clear:both;margin:1.25em 0 1.1875em}
80em,i{font-style:italic;line-height:inherit}
81strong,b{font-weight:bold;line-height:inherit}
82small{font-size:60%;line-height:inherit}
83code{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;font-weight:400;color:rgba(0,0,0,.9)}
84ul,ol,dl{line-height:1.6;margin-bottom:1.25em;list-style-position:outside;font-family:inherit}
85ul,ol{margin-left:1.5em}
86ul li ul,ul li ol{margin-left:1.25em;margin-bottom:0}
87ul.circle{list-style-type:circle}
88ul.disc{list-style-type:disc}
89ul.square{list-style-type:square}
90ul.circle ul:not([class]),ul.disc ul:not([class]),ul.square ul:not([class]){list-style:inherit}
91ol li ul,ol li ol{margin-left:1.25em;margin-bottom:0}
92dl dt{margin-bottom:.3125em;font-weight:bold}
93dl dd{margin-bottom:1.25em}
94blockquote{margin:0 0 1.25em;padding:.5625em 1.25em 0 1.1875em;border-left:1px solid #ddd}
95blockquote,blockquote p{line-height:1.6;color:rgba(0,0,0,.85)}
96@media screen and (min-width:768px){h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2}
97h1{font-size:2.75em}
98h2{font-size:2.3125em}
99h3,#toctitle,.sidebarblock>.content>.title{font-size:1.6875em}
100h4{font-size:1.4375em}}
101table{background:#fff;margin-bottom:1.25em;border:1px solid #dedede;word-wrap:normal}
102table thead,table tfoot{background:#f7f8f7}
103table thead tr th,table thead tr td,table tfoot tr th,table tfoot tr td{padding:.5em .625em .625em;font-size:inherit;color:rgba(0,0,0,.8);text-align:left}
104table tr th,table tr td{padding:.5625em .625em;font-size:inherit;color:rgba(0,0,0,.8)}
105table tr.even,table tr.alt{background:#f8f8f7}
106table thead tr th,table tfoot tr th,table tbody tr td,table tr td,table tfoot tr td{line-height:1.6}
107h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2;word-spacing:-.05em}
108h1 strong,h2 strong,h3 strong,#toctitle strong,.sidebarblock>.content>.title strong,h4 strong,h5 strong,h6 strong{font-weight:400}
109.center{margin-left:auto;margin-right:auto}
110.stretch{width:100%}
111.clearfix::before,.clearfix::after,.float-group::before,.float-group::after{content:" ";display:table}
112.clearfix::after,.float-group::after{clear:both}
113:not(pre).nobreak{word-wrap:normal}
114:not(pre).nowrap{white-space:nowrap}
115:not(pre).pre-wrap{white-space:pre-wrap}
116:not(pre):not([class^=L])>code{font-size:.9375em;font-style:normal!important;letter-spacing:0;padding:.1em .5ex;word-spacing:-.15em;background:#f7f7f8;border-radius:4px;line-height:1.45;text-rendering:optimizeSpeed}
117pre{color:rgba(0,0,0,.9);font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;line-height:1.45;text-rendering:optimizeSpeed}
118pre code,pre pre{color:inherit;font-size:inherit;line-height:inherit}
119pre>code{display:block}
120pre.nowrap,pre.nowrap pre{white-space:pre;word-wrap:normal}
121em em{font-style:normal}
122strong strong{font-weight:400}
123.keyseq{color:rgba(51,51,51,.8)}
124kbd{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;display:inline-block;color:rgba(0,0,0,.8);font-size:.65em;line-height:1.45;background:#f7f7f7;border:1px solid #ccc;border-radius:3px;box-shadow:0 1px 0 rgba(0,0,0,.2),inset 0 0 0 .1em #fff;margin:0 .15em;padding:.2em .5em;vertical-align:middle;position:relative;top:-.1em;white-space:nowrap}
125.keyseq kbd:first-child{margin-left:0}
126.keyseq kbd:last-child{margin-right:0}
127.menuseq,.menuref{color:#000}
128.menuseq b:not(.caret),.menuref{font-weight:inherit}
129.menuseq{word-spacing:-.02em}
130.menuseq b.caret{font-size:1.25em;line-height:.8}
131.menuseq i.caret{font-weight:bold;text-align:center;width:.45em}
132b.button::before,b.button::after{position:relative;top:-1px;font-weight:400}
133b.button::before{content:"[";padding:0 3px 0 2px}
134b.button::after{content:"]";padding:0 2px 0 3px}
135p a>code:hover{color:rgba(0,0,0,.9)}
136#header,#content,#footnotes,#footer{width:100%;margin:0 auto;max-width:62.5em;*zoom:1;position:relative;padding-left:.9375em;padding-right:.9375em}
137#header::before,#header::after,#content::before,#content::after,#footnotes::before,#footnotes::after,#footer::before,#footer::after{content:" ";display:table}
138#header::after,#content::after,#footnotes::after,#footer::after{clear:both}
139#content{margin-top:1.25em}
140#content::before{content:none}
141#header>h1:first-child{color:rgba(0,0,0,.85);margin-top:2.25rem;margin-bottom:0}
142#header>h1:first-child+#toc{margin-top:8px;border-top:1px solid #dddddf}
Junio C Hamanod6a33e42025-02-18 23:45:11[diff] [blame]143#header>h1:only-child{border-bottom:1px solid #dddddf;padding-bottom:8px}
Junio C Hamanob96f40a2024-08-01 00:57:25[diff] [blame]144#header .details{border-bottom:1px solid #dddddf;line-height:1.45;padding-top:.25em;padding-bottom:.25em;padding-left:.25em;color:rgba(0,0,0,.6);display:flex;flex-flow:row wrap}
145#header .details span:first-child{margin-left:-.125em}
146#header .details span.email a{color:rgba(0,0,0,.85)}
147#header .details br{display:none}
148#header .details br+span::before{content:"\00a0\2013\00a0"}
149#header .details br+span.author::before{content:"\00a0\22c5\00a0";color:rgba(0,0,0,.85)}
150#header .details br+span#revremark::before{content:"\00a0|\00a0"}
151#header #revnumber{text-transform:capitalize}
152#header #revnumber::after{content:"\00a0"}
153#content>h1:first-child:not([class]){color:rgba(0,0,0,.85);border-bottom:1px solid #dddddf;padding-bottom:8px;margin-top:0;padding-top:1rem;margin-bottom:1.25rem}
154#toc{border-bottom:1px solid #e7e7e9;padding-bottom:.5em}
155#toc>ul{margin-left:.125em}
156#toc ul.sectlevel0>li>a{font-style:italic}
157#toc ul.sectlevel0 ul.sectlevel1{margin:.5em 0}
158#toc ul{font-family:"Open Sans","DejaVu Sans",sans-serif;list-style-type:none}
159#toc li{line-height:1.3334;margin-top:.3334em}
160#toc a{text-decoration:none}
161#toc a:active{text-decoration:underline}
162#toctitle{color:#7a2518;font-size:1.2em}
163@media screen and (min-width:768px){#toctitle{font-size:1.375em}
164body.toc2{padding-left:15em;padding-right:0}
Junio C Hamanod6a33e42025-02-18 23:45:11[diff] [blame]165body.toc2 #header>h1:nth-last-child(2){border-bottom:1px solid #dddddf;padding-bottom:8px}
Junio C Hamanob96f40a2024-08-01 00:57:25[diff] [blame]166#toc.toc2{margin-top:0!important;background:#f8f8f7;position:fixed;width:15em;left:0;top:0;border-right:1px solid #e7e7e9;border-top-width:0!important;border-bottom-width:0!important;z-index:1000;padding:1.25em 1em;height:100%;overflow:auto}
167#toc.toc2 #toctitle{margin-top:0;margin-bottom:.8rem;font-size:1.2em}
168#toc.toc2>ul{font-size:.9em;margin-bottom:0}
169#toc.toc2 ul ul{margin-left:0;padding-left:1em}
170#toc.toc2 ul.sectlevel0 ul.sectlevel1{padding-left:0;margin-top:.5em;margin-bottom:.5em}
171body.toc2.toc-right{padding-left:0;padding-right:15em}
172body.toc2.toc-right #toc.toc2{border-right-width:0;border-left:1px solid #e7e7e9;left:auto;right:0}}
173@media screen and (min-width:1280px){body.toc2{padding-left:20em;padding-right:0}
174#toc.toc2{width:20em}
175#toc.toc2 #toctitle{font-size:1.375em}
176#toc.toc2>ul{font-size:.95em}
177#toc.toc2 ul ul{padding-left:1.25em}
178body.toc2.toc-right{padding-left:0;padding-right:20em}}
179#content #toc{border:1px solid #e0e0dc;margin-bottom:1.25em;padding:1.25em;background:#f8f8f7;border-radius:4px}
180#content #toc>:first-child{margin-top:0}
181#content #toc>:last-child{margin-bottom:0}
182#footer{max-width:none;background:rgba(0,0,0,.8);padding:1.25em}
183#footer-text{color:hsla(0,0%,100%,.8);line-height:1.44}
184#content{margin-bottom:.625em}
185.sect1{padding-bottom:.625em}
186@media screen and (min-width:768px){#content{margin-bottom:1.25em}
187.sect1{padding-bottom:1.25em}}
188.sect1:last-child{padding-bottom:0}
189.sect1+.sect1{border-top:1px solid #e7e7e9}
190#content h1>a.anchor,h2>a.anchor,h3>a.anchor,#toctitle>a.anchor,.sidebarblock>.content>.title>a.anchor,h4>a.anchor,h5>a.anchor,h6>a.anchor{position:absolute;z-index:1001;width:1.5ex;margin-left:-1.5ex;display:block;text-decoration:none!important;visibility:hidden;text-align:center;font-weight:400}
191#content h1>a.anchor::before,h2>a.anchor::before,h3>a.anchor::before,#toctitle>a.anchor::before,.sidebarblock>.content>.title>a.anchor::before,h4>a.anchor::before,h5>a.anchor::before,h6>a.anchor::before{content:"\00A7";font-size:.85em;display:block;padding-top:.1em}
192#content h1:hover>a.anchor,#content h1>a.anchor:hover,h2:hover>a.anchor,h2>a.anchor:hover,h3:hover>a.anchor,#toctitle:hover>a.anchor,.sidebarblock>.content>.title:hover>a.anchor,h3>a.anchor:hover,#toctitle>a.anchor:hover,.sidebarblock>.content>.title>a.anchor:hover,h4:hover>a.anchor,h4>a.anchor:hover,h5:hover>a.anchor,h5>a.anchor:hover,h6:hover>a.anchor,h6>a.anchor:hover{visibility:visible}
193#content h1>a.link,h2>a.link,h3>a.link,#toctitle>a.link,.sidebarblock>.content>.title>a.link,h4>a.link,h5>a.link,h6>a.link{color:#ba3925;text-decoration:none}
194#content h1>a.link:hover,h2>a.link:hover,h3>a.link:hover,#toctitle>a.link:hover,.sidebarblock>.content>.title>a.link:hover,h4>a.link:hover,h5>a.link:hover,h6>a.link:hover{color:#a53221}
195details,.audioblock,.imageblock,.literalblock,.listingblock,.stemblock,.videoblock{margin-bottom:1.25em}
196details{margin-left:1.25rem}
197details>summary{cursor:pointer;display:block;position:relative;line-height:1.6;margin-bottom:.625rem;outline:none;-webkit-tap-highlight-color:transparent}
198details>summary::-webkit-details-marker{display:none}
199details>summary::before{content:"";border:solid transparent;border-left:solid;border-width:.3em 0 .3em .5em;position:absolute;top:.5em;left:-1.25rem;transform:translateX(15%)}
200details[open]>summary::before{border:solid transparent;border-top:solid;border-width:.5em .3em 0;transform:translateY(15%)}
201details>summary::after{content:"";width:1.25rem;height:1em;position:absolute;top:.3em;left:-1.25rem}
202.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{text-rendering:optimizeLegibility;text-align:left;font-family:"Noto Serif","DejaVu Serif",serif;font-size:1rem;font-style:italic}
203table.tableblock.fit-content>caption.title{white-space:nowrap;width:0}
204.paragraph.lead>p,#preamble>.sectionbody>[class=paragraph]:first-of-type p{font-size:1.21875em;line-height:1.6;color:rgba(0,0,0,.85)}
205.admonitionblock>table{border-collapse:separate;border:0;background:none;width:100%}
206.admonitionblock>table td.icon{text-align:center;width:80px}
207.admonitionblock>table td.icon img{max-width:none}
208.admonitionblock>table td.icon .title{font-weight:bold;font-family:"Open Sans","DejaVu Sans",sans-serif;text-transform:uppercase}
209.admonitionblock>table td.content{padding-left:1.125em;padding-right:1.25em;border-left:1px solid #dddddf;color:rgba(0,0,0,.6);word-wrap:anywhere}
210.admonitionblock>table td.content>:last-child>:last-child{margin-bottom:0}
211.exampleblock>.content{border:1px solid #e6e6e6;margin-bottom:1.25em;padding:1.25em;background:#fff;border-radius:4px}
212.sidebarblock{border:1px solid #dbdbd6;margin-bottom:1.25em;padding:1.25em;background:#f3f3f2;border-radius:4px}
213.sidebarblock>.content>.title{color:#7a2518;margin-top:0;text-align:center}
214.exampleblock>.content>:first-child,.sidebarblock>.content>:first-child{margin-top:0}
215.exampleblock>.content>:last-child,.exampleblock>.content>:last-child>:last-child,.exampleblock>.content .olist>ol>li:last-child>:last-child,.exampleblock>.content .ulist>ul>li:last-child>:last-child,.exampleblock>.content .qlist>ol>li:last-child>:last-child,.sidebarblock>.content>:last-child,.sidebarblock>.content>:last-child>:last-child,.sidebarblock>.content .olist>ol>li:last-child>:last-child,.sidebarblock>.content .ulist>ul>li:last-child>:last-child,.sidebarblock>.content .qlist>ol>li:last-child>:last-child{margin-bottom:0}
216.literalblock pre,.listingblock>.content>pre{border-radius:4px;overflow-x:auto;padding:1em;font-size:.8125em}
217@media screen and (min-width:768px){.literalblock pre,.listingblock>.content>pre{font-size:.90625em}}
218@media screen and (min-width:1280px){.literalblock pre,.listingblock>.content>pre{font-size:1em}}
219.literalblock pre,.listingblock>.content>pre:not(.highlight),.listingblock>.content>pre[class=highlight],.listingblock>.content>pre[class^="highlight "]{background:#f7f7f8}
220.literalblock.output pre{color:#f7f7f8;background:rgba(0,0,0,.9)}
221.listingblock>.content{position:relative}
222.listingblock code[data-lang]::before{display:none;content:attr(data-lang);position:absolute;font-size:.75em;top:.425rem;right:.5rem;line-height:1;text-transform:uppercase;color:inherit;opacity:.5}
223.listingblock:hover code[data-lang]::before{display:block}
224.listingblock.terminal pre .command::before{content:attr(data-prompt);padding-right:.5em;color:inherit;opacity:.5}
225.listingblock.terminal pre .command:not([data-prompt])::before{content:"$"}
226.listingblock pre.highlightjs{padding:0}
227.listingblock pre.highlightjs>code{padding:1em;border-radius:4px}
228.listingblock pre.prettyprint{border-width:0}
229.prettyprint{background:#f7f7f8}
230pre.prettyprint .linenums{line-height:1.45;margin-left:2em}
231pre.prettyprint li{background:none;list-style-type:inherit;padding-left:0}
232pre.prettyprint li code[data-lang]::before{opacity:1}
233pre.prettyprint li:not(:first-child) code[data-lang]::before{display:none}
234table.linenotable{border-collapse:separate;border:0;margin-bottom:0;background:none}
235table.linenotable td[class]{color:inherit;vertical-align:top;padding:0;line-height:inherit;white-space:normal}
236table.linenotable td.code{padding-left:.75em}
237table.linenotable td.linenos,pre.pygments .linenos{border-right:1px solid;opacity:.35;padding-right:.5em;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none}
238pre.pygments span.linenos{display:inline-block;margin-right:.75em}
239.quoteblock{margin:0 1em 1.25em 1.5em;display:table}
240.quoteblock:not(.excerpt)>.title{margin-left:-1.5em;margin-bottom:.75em}
241.quoteblock blockquote,.quoteblock p{color:rgba(0,0,0,.85);font-size:1.15rem;line-height:1.75;word-spacing:.1em;letter-spacing:0;font-style:italic;text-align:justify}
242.quoteblock blockquote{margin:0;padding:0;border:0}
243.quoteblock blockquote::before{content:"\201c";float:left;font-size:2.75em;font-weight:bold;line-height:.6em;margin-left:-.6em;color:#7a2518;text-shadow:0 1px 2px rgba(0,0,0,.1)}
244.quoteblock blockquote>.paragraph:last-child p{margin-bottom:0}
245.quoteblock .attribution{margin-top:.75em;margin-right:.5ex;text-align:right}
246.verseblock{margin:0 1em 1.25em}
247.verseblock pre{font-family:"Open Sans","DejaVu Sans",sans-serif;font-size:1.15rem;color:rgba(0,0,0,.85);font-weight:300;text-rendering:optimizeLegibility}
248.verseblock pre strong{font-weight:400}
249.verseblock .attribution{margin-top:1.25rem;margin-left:.5ex}
250.quoteblock .attribution,.verseblock .attribution{font-size:.9375em;line-height:1.45;font-style:italic}
251.quoteblock .attribution br,.verseblock .attribution br{display:none}
252.quoteblock .attribution cite,.verseblock .attribution cite{display:block;letter-spacing:-.025em;color:rgba(0,0,0,.6)}
253.quoteblock.abstract blockquote::before,.quoteblock.excerpt blockquote::before,.quoteblock .quoteblock blockquote::before{display:none}
254.quoteblock.abstract blockquote,.quoteblock.abstract p,.quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{line-height:1.6;word-spacing:0}
255.quoteblock.abstract{margin:0 1em 1.25em;display:block}
256.quoteblock.abstract>.title{margin:0 0 .375em;font-size:1.15em;text-align:center}
257.quoteblock.excerpt>blockquote,.quoteblock .quoteblock{padding:0 0 .25em 1em;border-left:.25em solid #dddddf}
258.quoteblock.excerpt,.quoteblock .quoteblock{margin-left:0}
259.quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{color:inherit;font-size:1.0625rem}
260.quoteblock.excerpt .attribution,.quoteblock .quoteblock .attribution{color:inherit;font-size:.85rem;text-align:left;margin-right:0}
261p.tableblock:last-child{margin-bottom:0}
262td.tableblock>.content{margin-bottom:1.25em;word-wrap:anywhere}
263td.tableblock>.content>:last-child{margin-bottom:-1.25em}
264table.tableblock,th.tableblock,td.tableblock{border:0 solid #dedede}
265table.grid-all>*>tr>*{border-width:1px}
266table.grid-cols>*>tr>*{border-width:0 1px}
267table.grid-rows>*>tr>*{border-width:1px 0}
268table.frame-all{border-width:1px}
269table.frame-ends{border-width:1px 0}
270table.frame-sides{border-width:0 1px}
271table.frame-none>colgroup+*>:first-child>*,table.frame-sides>colgroup+*>:first-child>*{border-top-width:0}
272table.frame-none>:last-child>:last-child>*,table.frame-sides>:last-child>:last-child>*{border-bottom-width:0}
273table.frame-none>*>tr>:first-child,table.frame-ends>*>tr>:first-child{border-left-width:0}
274table.frame-none>*>tr>:last-child,table.frame-ends>*>tr>:last-child{border-right-width:0}
275table.stripes-all>*>tr,table.stripes-odd>*>tr:nth-of-type(odd),table.stripes-even>*>tr:nth-of-type(even),table.stripes-hover>*>tr:hover{background:#f8f8f7}
276th.halign-left,td.halign-left{text-align:left}
277th.halign-right,td.halign-right{text-align:right}
278th.halign-center,td.halign-center{text-align:center}
279th.valign-top,td.valign-top{vertical-align:top}
280th.valign-bottom,td.valign-bottom{vertical-align:bottom}
281th.valign-middle,td.valign-middle{vertical-align:middle}
282table thead th,table tfoot th{font-weight:bold}
283tbody tr th{background:#f7f8f7}
284tbody tr th,tbody tr th p,tfoot tr th,tfoot tr th p{color:rgba(0,0,0,.8);font-weight:bold}
285p.tableblock>code:only-child{background:none;padding:0}
286p.tableblock{font-size:1em}
287ol{margin-left:1.75em}
288ul li ol{margin-left:1.5em}
289dl dd{margin-left:1.125em}
290dl dd:last-child,dl dd:last-child>:last-child{margin-bottom:0}
291li p,ul dd,ol dd,.olist .olist,.ulist .ulist,.ulist .olist,.olist .ulist{margin-bottom:.625em}
292ul.checklist,ul.none,ol.none,ul.no-bullet,ol.no-bullet,ol.unnumbered,ul.unstyled,ol.unstyled{list-style-type:none}
293ul.no-bullet,ol.no-bullet,ol.unnumbered{margin-left:.625em}
294ul.unstyled,ol.unstyled{margin-left:0}
295li>p:empty:only-child::before{content:"";display:inline-block}
296ul.checklist>li>p:first-child{margin-left:-1em}
297ul.checklist>li>p:first-child>.fa-square-o:first-child,ul.checklist>li>p:first-child>.fa-check-square-o:first-child{width:1.25em;font-size:.8em;position:relative;bottom:.125em}
298ul.checklist>li>p:first-child>input[type=checkbox]:first-child{margin-right:.25em}
299ul.inline{display:flex;flex-flow:row wrap;list-style:none;margin:0 0 .625em -1.25em}
300ul.inline>li{margin-left:1.25em}
301.unstyled dl dt{font-weight:400;font-style:normal}
302ol.arabic{list-style-type:decimal}
303ol.decimal{list-style-type:decimal-leading-zero}
304ol.loweralpha{list-style-type:lower-alpha}
305ol.upperalpha{list-style-type:upper-alpha}
306ol.lowerroman{list-style-type:lower-roman}
307ol.upperroman{list-style-type:upper-roman}
308ol.lowergreek{list-style-type:lower-greek}
309.hdlist>table,.colist>table{border:0;background:none}
310.hdlist>table>tbody>tr,.colist>table>tbody>tr{background:none}
311td.hdlist1,td.hdlist2{vertical-align:top;padding:0 .625em}
312td.hdlist1{font-weight:bold;padding-bottom:1.25em}
313td.hdlist2{word-wrap:anywhere}
314.literalblock+.colist,.listingblock+.colist{margin-top:-.5em}
315.colist td:not([class]):first-child{padding:.4em .75em 0;line-height:1;vertical-align:top}
316.colist td:not([class]):first-child img{max-width:none}
317.colist td:not([class]):last-child{padding:.25em 0}
318.thumb,.th{line-height:0;display:inline-block;border:4px solid #fff;box-shadow:0 0 0 1px #ddd}
319.imageblock.left{margin:.25em .625em 1.25em 0}
320.imageblock.right{margin:.25em 0 1.25em .625em}
321.imageblock>.title{margin-bottom:0}
322.imageblock.thumb,.imageblock.th{border-width:6px}
323.imageblock.thumb>.title,.imageblock.th>.title{padding:0 .125em}
324.image.left,.image.right{margin-top:.25em;margin-bottom:.25em;display:inline-block;line-height:0}
325.image.left{margin-right:.625em}
326.image.right{margin-left:.625em}
327a.image{text-decoration:none;display:inline-block}
328a.image object{pointer-events:none}
329sup.footnote,sup.footnoteref{font-size:.875em;position:static;vertical-align:super}
330sup.footnote a,sup.footnoteref a{text-decoration:none}
Junio C Hamanod6a33e42025-02-18 23:45:11[diff] [blame]331sup.footnote a:active,sup.footnoteref a:active,#footnotes .footnote a:first-of-type:active{text-decoration:underline}
Junio C Hamanob96f40a2024-08-01 00:57:25[diff] [blame]332#footnotes{padding-top:.75em;padding-bottom:.75em;margin-bottom:.625em}
333#footnotes hr{width:20%;min-width:6.25em;margin:-.25em 0 .75em;border-width:1px 0 0}
334#footnotes .footnote{padding:0 .375em 0 .225em;line-height:1.3334;font-size:.875em;margin-left:1.2em;margin-bottom:.2em}
335#footnotes .footnote a:first-of-type{font-weight:bold;text-decoration:none;margin-left:-1.05em}
336#footnotes .footnote:last-of-type{margin-bottom:0}
337#content #footnotes{margin-top:-.625em;margin-bottom:0;padding:.75em 0}
338div.unbreakable{page-break-inside:avoid}
339.big{font-size:larger}
340.small{font-size:smaller}
341.underline{text-decoration:underline}
342.overline{text-decoration:overline}
343.line-through{text-decoration:line-through}
344.aqua{color:#00bfbf}
345.aqua-background{background:#00fafa}
346.black{color:#000}
347.black-background{background:#000}
348.blue{color:#0000bf}
349.blue-background{background:#0000fa}
350.fuchsia{color:#bf00bf}
351.fuchsia-background{background:#fa00fa}
352.gray{color:#606060}
353.gray-background{background:#7d7d7d}
354.green{color:#006000}
355.green-background{background:#007d00}
356.lime{color:#00bf00}
357.lime-background{background:#00fa00}
358.maroon{color:#600000}
359.maroon-background{background:#7d0000}
360.navy{color:#000060}
361.navy-background{background:#00007d}
362.olive{color:#606000}
363.olive-background{background:#7d7d00}
364.purple{color:#600060}
365.purple-background{background:#7d007d}
366.red{color:#bf0000}
367.red-background{background:#fa0000}
368.silver{color:#909090}
369.silver-background{background:#bcbcbc}
370.teal{color:#006060}
371.teal-background{background:#007d7d}
372.white{color:#bfbfbf}
373.white-background{background:#fafafa}
374.yellow{color:#bfbf00}
375.yellow-background{background:#fafa00}
376span.icon>.fa{cursor:default}
377a span.icon>.fa{cursor:inherit}
378.admonitionblock td.icon [class^="fa icon-"]{font-size:2.5em;text-shadow:1px 1px 2px rgba(0,0,0,.5);cursor:default}
379.admonitionblock td.icon .icon-note::before{content:"\f05a";color:#19407c}
380.admonitionblock td.icon .icon-tip::before{content:"\f0eb";text-shadow:1px 1px 2px rgba(155,155,0,.8);color:#111}
381.admonitionblock td.icon .icon-warning::before{content:"\f071";color:#bf6900}
382.admonitionblock td.icon .icon-caution::before{content:"\f06d";color:#bf3400}
383.admonitionblock td.icon .icon-important::before{content:"\f06a";color:#bf0000}
384.conum[data-value]{display:inline-block;color:#fff!important;background:rgba(0,0,0,.8);border-radius:50%;text-align:center;font-size:.75em;width:1.67em;height:1.67em;line-height:1.67em;font-family:"Open Sans","DejaVu Sans",sans-serif;font-style:normal;font-weight:bold}
385.conum[data-value] *{color:#fff!important}
386.conum[data-value]+b{display:none}
387.conum[data-value]::after{content:attr(data-value)}
388pre .conum[data-value]{position:relative;top:-.125em}
389b.conum *{color:inherit!important}
390.conum:not([data-value]):empty{display:none}
391dt,th.tableblock,td.content,div.footnote{text-rendering:optimizeLegibility}
392h1,h2,p,td.content,span.alt,summary{letter-spacing:-.01em}
393p strong,td.content strong,div.footnote strong{letter-spacing:-.005em}
394p,blockquote,dt,td.content,td.hdlist1,span.alt,summary{font-size:1.0625rem}
395p{margin-bottom:1.25rem}
396.sidebarblock p,.sidebarblock dt,.sidebarblock td.content,p.tableblock{font-size:1em}
397.exampleblock>.content{background:#fffef7;border-color:#e0e0dc;box-shadow:0 1px 4px #e0e0dc}
398.print-only{display:none!important}
399@page{margin:1.25cm .75cm}
400@media print{*{box-shadow:none!important;text-shadow:none!important}
401html{font-size:80%}
402a{color:inherit!important;text-decoration:underline!important}
403a.bare,a[href^="#"],a[href^="mailto:"]{text-decoration:none!important}
404a[href^="http:"]:not(.bare)::after,a[href^="https:"]:not(.bare)::after{content:"(" attr(href) ")";display:inline-block;font-size:.875em;padding-left:.25em}
405abbr[title]{border-bottom:1px dotted}
406abbr[title]::after{content:" (" attr(title) ")"}
407pre,blockquote,tr,img,object,svg{page-break-inside:avoid}
408thead{display:table-header-group}
409svg{max-width:100%}
410p,blockquote,dt,td.content{font-size:1em;orphans:3;widows:3}
411h2,h3,#toctitle,.sidebarblock>.content>.title{page-break-after:avoid}
412#header,#content,#footnotes,#footer{max-width:none}
413#toc,.sidebarblock,.exampleblock>.content{background:none!important}
414#toc{border-bottom:1px solid #dddddf!important;padding-bottom:0!important}
415body.book #header{text-align:center}
416body.book #header>h1:first-child{border:0!important;margin:2.5em 0 1em}
417body.book #header .details{border:0!important;display:block;padding:0!important}
418body.book #header .details span:first-child{margin-left:0!important}
419body.book #header .details br{display:block}
420body.book #header .details br+span::before{content:none!important}
421body.book #toc{border:0!important;text-align:left!important;padding:0!important;margin:0!important}
422body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-break-before:always}
423.listingblock code[data-lang]::before{display:block}
424#footer{padding:0 .9375em}
425.hide-on-print{display:none!important}
426.print-only{display:block!important}
427.hide-for-print{display:none!important}
428.show-for-print{display:inherit!important}}
429@media amzn-kf8,print{#header>h1:first-child{margin-top:1.25rem}
430.sect1{padding:0!important}
431.sect1+.sect1{border:0}
432#footer{background:none}
433#footer-text{color:rgba(0,0,0,.6);font-size:.9em}}
434@media amzn-kf8{#header,#content,#footnotes,#footer{padding:0}}
435</style>
436<style>
437pre>code {
438 display: inline;
439}
440</style>
441</head>
442<body class="manpage">
443<div id="header">
444<h1>gitcli(7) Manual Page</h1>
445<h2 id="_name">NAME</h2>
446<div class="sectionbody">
447<p>gitcli - Git command-line interface and conventions</p>
448</div>
449</div>
450<div id="content">
451<div class="sect1">
452<h2 id="_synopsis">SYNOPSIS</h2>
453<div class="sectionbody">
454<div class="paragraph">
455<p>gitcli</p>
456</div>
457</div>
458</div>
459<div class="sect1">
460<h2 id="_description">DESCRIPTION</h2>
461<div class="sectionbody">
462<div class="paragraph">
463<p>This manual describes the convention used throughout Git CLI.</p>
464</div>
465<div class="paragraph">
466<p>Many commands take revisions (most often "commits", but sometimes
467"tree-ish", depending on the context and command) and paths as their
468arguments. Here are the rules:</p>
469</div>
470<div class="ulist">
471<ul>
472<li>
473<p>Options come first and then args.
474A subcommand may take dashed options (which may take their own
475arguments, e.g. "--max-parents 2") and arguments. You SHOULD
476give dashed options first and then arguments. Some commands may
477accept dashed options after you have already given non-option
478arguments (which may make the command ambiguous), but you should
479not rely on it (because eventually we may find a way to fix
480these ambiguities by enforcing the "options then args" rule).</p>
481</li>
482<li>
483<p>Revisions come first and then paths.
Junio C Hamanodc392382024-10-11 18:57:29[diff] [blame]484E.g. in <code>git</code> <code>diff</code> <code>v1.0</code> <code>v2.0</code> <code>arch/x86</code> <code>include/asm-x86</code>,
Junio C Hamanob96f40a2024-08-01 00:57:25[diff] [blame]485<code>v1.0</code> and <code>v2.0</code> are revisions and <code>arch/x86</code> and <code>include/asm-x86</code>
486are paths.</p>
487</li>
488<li>
489<p>When an argument can be misunderstood as either a revision or a path,
490they can be disambiguated by placing <code>--</code> between them.
Junio C Hamanodc392382024-10-11 18:57:29[diff] [blame]491E.g. <code>git</code> <code>diff</code> <code>--</code> <code>HEAD</code> is, "I have a file called HEAD in my work
Junio C Hamanob96f40a2024-08-01 00:57:25[diff] [blame]492tree. Please show changes between the version I staged in the index
493and what I have in the work tree for that file", not "show the difference
494between the HEAD commit and the work tree as a whole". You can say
Junio C Hamanodc392382024-10-11 18:57:29[diff] [blame]495<code>git</code> <code>diff</code> <code>HEAD</code> <code>--</code> to ask for the latter.</p>
Junio C Hamanob96f40a2024-08-01 00:57:25[diff] [blame]496</li>
497<li>
498<p>Without disambiguating <code>--</code>, Git makes a reasonable guess, but errors
499out and asks you to disambiguate when ambiguous. E.g. if you have a
Junio C Hamanodc392382024-10-11 18:57:29[diff] [blame]500file called HEAD in your work tree, <code>git</code> <code>diff</code> <code>HEAD</code> is ambiguous, and
501you have to say either <code>git</code> <code>diff</code> <code>HEAD</code> <code>--</code> or <code>git</code> <code>diff</code> <code>--</code> <code>HEAD</code> to
Junio C Hamanob96f40a2024-08-01 00:57:25[diff] [blame]502disambiguate.</p>
503</li>
504<li>
505<p>Because <code>--</code> disambiguates revisions and paths in some commands, it
506cannot be used for those commands to separate options and revisions.
507You can use <code>--end-of-options</code> for this (it also works for commands
508that do not distinguish between revisions in paths, in which case it
509is simply an alias for <code>--</code>).</p>
510<div class="paragraph">
511<p>When writing a script that is expected to handle random user-input, it is
512a good practice to make it explicit which arguments are which by placing
513disambiguating <code>--</code> at appropriate places.</p>
514</div>
515</li>
516<li>
517<p>Many commands allow wildcards in paths, but you need to protect
518them from getting globbed by the shell. These two mean different
519things:</p>
520<div class="listingblock">
521<div class="content">
522<pre>$ git restore *.c
523$ git restore \*.c</pre>
524</div>
525</div>
526<div class="paragraph">
527<p>The former lets your shell expand the fileglob, and you are asking
528the dot-C files in your working tree to be overwritten with the version
Junio C Hamanoe03f5992025-04-23 22:24:29[diff] [blame]529in the index. The latter passes the <code>*.c</code> to Git, and you are asking
Junio C Hamanob96f40a2024-08-01 00:57:25[diff] [blame]530the paths in the index that match the pattern to be checked out to your
Junio C Hamanodc392382024-10-11 18:57:29[diff] [blame]531working tree. After running <code>git</code> <code>add</code> <code>hello.c</code>; <code>rm</code> <code>hello.c</code>, you will <em>not</em>
Junio C Hamanob96f40a2024-08-01 00:57:25[diff] [blame]532see <code>hello.c</code> in your working tree with the former, but with the latter
533you will.</p>
534</div>
535</li>
536<li>
537<p>Just as the filesystem <em>.</em> (period) refers to the current directory,
538using a <em>.</em> as a repository name in Git (a dot-repository) is a relative
539path and means your current repository.</p>
540</li>
541</ul>
542</div>
543<div class="paragraph">
544<p>Here are the rules regarding the "flags" that you should follow when you are
545scripting Git:</p>
546</div>
547<div class="ulist">
548<ul>
549<li>
Junio C Hamanodc392382024-10-11 18:57:29[diff] [blame]550<p>Splitting short options to separate words (prefer <code>git</code> <code>foo</code> <code>-a</code> <code>-b</code>
551to <code>git</code> <code>foo</code> <code>-ab</code>, the latter may not even work).</p>
Junio C Hamanob96f40a2024-08-01 00:57:25[diff] [blame]552</li>
553<li>
554<p>When a command-line option takes an argument, use the <em>stuck</em> form. In
Junio C Hamanodc392382024-10-11 18:57:29[diff] [blame]555other words, write <code>git</code> <code>foo</code> <code>-oArg</code> instead of <code>git</code> <code>foo</code> <code>-o</code> <code>Arg</code> for short
556options, and <code>git</code> <code>foo</code> <code>--long-opt=Arg</code> instead of <code>git</code> <code>foo</code> <code>--long-opt</code> <code>Arg</code>
Junio C Hamanob96f40a2024-08-01 00:57:25[diff] [blame]557for long options. An option that takes optional option-argument must be
558written in the <em>stuck</em> form.</p>
559</li>
560<li>
Junio C Hamano0dfbbf32024-12-10 12:09:06[diff] [blame]561<p>Despite the above suggestion, when Arg is a path relative to the
Junio C Hamanoef57b062025-01-06 18:24:18[diff] [blame]562home directory of a user, e.g. <code>~/directory/file</code> or <code>~u/d/f</code>, you
Junio C Hamano0dfbbf32024-12-10 12:09:06[diff] [blame]563may want to use the separate form, e.g. <code>git</code> <code>foo</code> <code>--file</code> <code>~/mine</code>,
564not <code>git</code> <code>foo</code> <code>--file=~/mine</code>. The shell will expand <code>~/</code> in the
565former to your home directory, but most shells keep the tilde in
566the latter. Some of our commands know how to tilde-expand the
567option value even when given in the stuck form, but not all of
568them do.</p>
569</li>
570<li>
Junio C Hamanob96f40a2024-08-01 00:57:25[diff] [blame]571<p>When you give a revision parameter to a command, make sure the parameter is
572not ambiguous with a name of a file in the work tree. E.g. do not write
Junio C Hamanodc392382024-10-11 18:57:29[diff] [blame]573<code>git</code> <code>log</code> <code>-1</code> <code>HEAD</code> but write <code>git</code> <code>log</code> <code>-1</code> <code>HEAD</code> <code>--</code>; the former will not work
Junio C Hamanob96f40a2024-08-01 00:57:25[diff] [blame]574if you happen to have a file called <code>HEAD</code> in the work tree.</p>
575</li>
576<li>
577<p>Many commands allow a long option <code>--option</code> to be abbreviated
578only to their unique prefix (e.g. if there is no other option
579whose name begins with <code>opt</code>, you may be able to spell <code>--opt</code> to
580invoke the <code>--option</code> flag), but you should fully spell them out
581when writing your scripts; later versions of Git may introduce a
582new option whose name shares the same prefix, e.g. <code>--optimize</code>,
583to make a short prefix that used to be unique no longer unique.</p>
584</li>
585</ul>
586</div>
587</div>
588</div>
589<div class="sect1">
590<h2 id="_enhanced_option_parser">ENHANCED OPTION PARSER</h2>
591<div class="sectionbody">
592<div class="paragraph">
593<p>From the Git 1.5.4 series and further, many Git commands (not all of them at the
594time of the writing though) come with an enhanced option parser.</p>
595</div>
596<div class="paragraph">
597<p>Here is a list of the facilities provided by this option parser.</p>
598</div>
599<div class="sect2">
600<h3 id="_magic_options">Magic Options</h3>
601<div class="paragraph">
602<p>Commands which have the enhanced option parser activated all understand a
603couple of magic command-line options:</p>
604</div>
605<div class="dlist">
606<dl>
607<dt class="hdlist1">-h</dt>
608<dd>
609<p>gives a pretty printed usage of the command.</p>
610<div class="listingblock">
611<div class="content">
612<pre>$ git describe -h
613usage: git describe [&lt;options&gt;] &lt;commit-ish&gt;*
614 or: git describe [&lt;options&gt;] --dirty
615
616 --contains find the tag that comes after the commit
617 --debug debug search strategy on stderr
618 --all use any ref
619 --tags use any tag, even unannotated
620 --long always use long format
621 --abbrev[=&lt;n&gt;] use &lt;n&gt; digits to display SHA-1s</pre>
622</div>
623</div>
624<div class="paragraph">
Junio C Hamanodc392382024-10-11 18:57:29[diff] [blame]625<p>Note that some subcommand (e.g. <code>git</code> <code>grep</code>) may behave differently
626when there are things on the command line other than <code>-h</code>, but <code>git</code>
627<code>subcmd</code> <code>-h</code> without anything else on the command line is meant to
Junio C Hamanob96f40a2024-08-01 00:57:25[diff] [blame]628consistently give the usage.</p>
629</div>
630</dd>
631<dt class="hdlist1">--help-all</dt>
632<dd>
633<p>Some Git commands take options that are only used for plumbing or that
634are deprecated, and such options are hidden from the default usage. This
635option gives the full list of options.</p>
636</dd>
637</dl>
638</div>
639</div>
640<div class="sect2">
641<h3 id="_negating_options">Negating options</h3>
642<div class="paragraph">
643<p>Options with long option names can be negated by prefixing <code>--no-</code>. For
Junio C Hamanodc392382024-10-11 18:57:29[diff] [blame]644example, <code>git</code> <code>branch</code> has the option <code>--track</code> which is <em>on</em> by default. You
Junio C Hamanob96f40a2024-08-01 00:57:25[diff] [blame]645can use <code>--no-track</code> to override that behaviour. The same goes for <code>--color</code>
646and <code>--no-color</code>.</p>
647</div>
648</div>
649<div class="sect2">
Junio C Hamanoa45cb072025-01-24 17:51:33[diff] [blame]650<h3 id="_options_trump_configuration_and_environment">Options trump configuration and environment</h3>
651<div class="paragraph">
652<p>When there is a configuration variable or an environment variable
653that tweak the behaviour of an aspect of a Git command, and also a
654command line option that tweaks the same, the command line option
655overrides what the configuration and/or environment variable say.</p>
656</div>
657<div class="paragraph">
658<p>For example, the <code>user.name</code> configuration variable is used to
659specify the human-readable name used by the <code>git</code> <code>commit</code> command to
660record the author and the committer name in a newly created commit.
661The <code>GIT_AUTHOR_NAME</code> environment variable, if set, takes precedence
662when deciding what author name to record. The <code>--author=</code><em>&lt;author&gt;</em>
663command line option of the <code>git</code> <code>commit</code> command, when given, takes
664precedence over these two sources of information.</p>
665</div>
666</div>
667<div class="sect2">
Junio C Hamanob96f40a2024-08-01 00:57:25[diff] [blame]668<h3 id="_aggregating_short_options">Aggregating short options</h3>
669<div class="paragraph">
670<p>Commands that support the enhanced option parser allow you to aggregate short
Junio C Hamanodc392382024-10-11 18:57:29[diff] [blame]671options. This means that you can for example use <code>git</code> <code>rm</code> <code>-rf</code> or
672<code>git</code> <code>clean</code> <code>-fdx</code>.</p>
Junio C Hamanob96f40a2024-08-01 00:57:25[diff] [blame]673</div>
674</div>
675<div class="sect2">
676<h3 id="_abbreviating_long_options">Abbreviating long options</h3>
677<div class="paragraph">
678<p>Commands that support the enhanced option parser accepts unique
679prefix of a long option as if it is fully spelled out, but use this
Junio C Hamanodc392382024-10-11 18:57:29[diff] [blame]680with a caution. For example, <code>git</code> <code>commit</code> <code>--amen</code> behaves as if you
681typed <code>git</code> <code>commit</code> <code>--amend</code>, but that is true only until a later version
Junio C Hamanob96f40a2024-08-01 00:57:25[diff] [blame]682of Git introduces another option that shares the same prefix,
Junio C Hamanodc392382024-10-11 18:57:29[diff] [blame]683e.g. <code>git</code> <code>commit</code> <code>--amenity</code> option.</p>
Junio C Hamanob96f40a2024-08-01 00:57:25[diff] [blame]684</div>
685</div>
686<div class="sect2">
687<h3 id="_separating_argument_from_the_option">Separating argument from the option</h3>
688<div class="paragraph">
689<p>You can write the mandatory option parameter to an option as a separate
690word on the command line. That means that all the following uses work:</p>
691</div>
692<div class="listingblock">
693<div class="content">
694<pre>$ git foo --long-opt=Arg
695$ git foo --long-opt Arg
696$ git foo -oArg
697$ git foo -o Arg</pre>
698</div>
699</div>
700<div class="paragraph">
701<p>However, this is <strong>NOT</strong> allowed for switches with an optional value, where the
702<em>stuck</em> form must be used:</p>
703</div>
704<div class="listingblock">
705<div class="content">
706<pre>$ git describe --abbrev HEAD # correct
707$ git describe --abbrev=10 HEAD # correct
708$ git describe --abbrev 10 HEAD # NOT WHAT YOU MEANT</pre>
709</div>
710</div>
711</div>
712</div>
713</div>
714<div class="sect1">
715<h2 id="_notes_on_frequently_confused_options">NOTES ON FREQUENTLY CONFUSED OPTIONS</h2>
716<div class="sectionbody">
717<div class="paragraph">
718<p>Many commands that can work on files in the working tree
719and/or in the index can take <code>--cached</code> and/or <code>--index</code>
720options. Sometimes people incorrectly think that, because
721the index was originally called cache, these two are
722synonyms. They are <strong>not</strong>&#8201;&#8212;&#8201;these two options mean very
723different things.</p>
724</div>
725<div class="ulist">
726<ul>
727<li>
728<p>The <code>--cached</code> option is used to ask a command that
729usually works on files in the working tree to <strong>only</strong> work
Junio C Hamanodc392382024-10-11 18:57:29[diff] [blame]730with the index. For example, <code>git</code> <code>grep</code>, when used
Junio C Hamanob96f40a2024-08-01 00:57:25[diff] [blame]731without a commit to specify from which commit to look for
732strings in, usually works on files in the working tree,
733but with the <code>--cached</code> option, it looks for strings in
734the index.</p>
735</li>
736<li>
737<p>The <code>--index</code> option is used to ask a command that
738usually works on files in the working tree to <strong>also</strong>
Junio C Hamanodc392382024-10-11 18:57:29[diff] [blame]739affect the index. For example, <code>git</code> <code>stash</code> <code>apply</code> usually
Junio C Hamanob96f40a2024-08-01 00:57:25[diff] [blame]740merges changes recorded in a stash entry to the working tree,
741but with the <code>--index</code> option, it also merges changes to
742the index as well.</p>
743</li>
744</ul>
745</div>
746<div class="paragraph">
Junio C Hamanodc392382024-10-11 18:57:29[diff] [blame]747<p><code>git</code> <code>apply</code> command can be used with <code>--cached</code> and
Junio C Hamanob96f40a2024-08-01 00:57:25[diff] [blame]748<code>--index</code> (but not at the same time). Usually the command
749only affects the files in the working tree, but with
750<code>--index</code>, it patches both the files and their index
751entries, and with <code>--cached</code>, it modifies only the index
752entries.</p>
753</div>
754<div class="paragraph">
755<p>See also <a href="https://lore.kernel.org/git/7v64clg5u9.fsf@assigned-by-dhcp.cox.net/" class="bare">https://lore.kernel.org/git/7v64clg5u9.fsf@assigned-by-dhcp.cox.net/</a> and
756<a href="https://lore.kernel.org/git/7vy7ej9g38.fsf@gitster.siamese.dyndns.org/" class="bare">https://lore.kernel.org/git/7vy7ej9g38.fsf@gitster.siamese.dyndns.org/</a> for further
757information.</p>
758</div>
759<div class="paragraph">
760<p>Some other commands that also work on files in the working tree and/or
761in the index can take <code>--staged</code> and/or <code>--worktree</code>.</p>
762</div>
763<div class="ulist">
764<ul>
765<li>
766<p><code>--staged</code> is exactly like <code>--cached</code>, which is used to ask a
767command to only work on the index, not the working tree.</p>
768</li>
769<li>
770<p><code>--worktree</code> is the opposite, to ask a command to work on the
771working tree only, not the index.</p>
772</li>
773<li>
774<p>The two options can be specified together to ask a command to work
775on both the index and the working tree.</p>
776</li>
777</ul>
778</div>
779</div>
780</div>
781<div class="sect1">
782<h2 id="_git">GIT</h2>
783<div class="sectionbody">
784<div class="paragraph">
785<p>Part of the <a href="git.html">git(1)</a> suite</p>
786</div>
787</div>
788</div>
789</div>
790<div id="footer">
791<div id="footer-text">
Junio C Hamano1cc68cc2025-08-04 16:37:24[diff] [blame]792Last updated 2025-06-20 18:10:42 -0700
Junio C Hamanob96f40a2024-08-01 00:57:25[diff] [blame]793</div>
794</div>
795</body>
796</html>