| blob | 953b5314a18a66341c90e1e2fcb5f63f59843e1f |
1 '\" t
2 .\" Title: gitcli
3 .\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
4 .\" Generator: DocBook XSL Stylesheets v1.79.2 <http://docbook.sf.net/>
5 .\" Date: 2024-08-21
6 .\" Manual: Git Manual
7 .\" Source: Git 2.46.0.288.g3a7362eb9f
8 .\" Language: English
9 .\"
10 .TH "GITCLI" "7" "2024-08-21" "Git 2\&.46\&.0\&.288\&.g3a7362" "Git Manual"
11 .\" -----------------------------------------------------------------
12 .\" * Define some portability stuff
13 .\" -----------------------------------------------------------------
14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
15 .\" http://bugs.debian.org/507673
16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
18 .ie \n(.g .ds Aq \(aq
19 .el .ds Aq '
20 .\" -----------------------------------------------------------------
21 .\" * set default formatting
22 .\" -----------------------------------------------------------------
23 .\" disable hyphenation
24 .nh
25 .\" disable justification (adjust text to left margin only)
26 .ad l
27 .\" -----------------------------------------------------------------
28 .\" * MAIN CONTENT STARTS HERE *
29 .\" -----------------------------------------------------------------
30 .SH "NAME"
31 gitcli \- Git command\-line interface and conventions
32 .SH "SYNOPSIS"
33 .sp
34 gitcli
35 .SH "DESCRIPTION"
36 .sp
37 This manual describes the convention used throughout Git CLI\&.
38 .sp
39 Many commands take revisions (most often "commits", but sometimes "tree\-ish", depending on the context and command) and paths as their arguments\&. Here are the rules:
40 .sp
41 .RS 4
42 .ie n \{\
43 \h'-04'\(bu\h'+03'\c
44 .\}
45 .el \{\
46 .sp -1
47 .IP \(bu 2.3
48 .\}
49 Options come first and then args\&. A subcommand may take dashed options (which may take their own arguments, e\&.g\&. "\-\-max\-parents 2") and arguments\&. You SHOULD give dashed options first and then arguments\&. Some commands may accept dashed options after you have already given non\-option arguments (which may make the command ambiguous), but you should not rely on it (because eventually we may find a way to fix these ambiguities by enforcing the "options then args" rule)\&.
50 .RE
51 .sp
52 .RS 4
53 .ie n \{\
54 \h'-04'\(bu\h'+03'\c
55 .\}
56 .el \{\
57 .sp -1
58 .IP \(bu 2.3
59 .\}
60 Revisions come first and then paths\&. E\&.g\&. in
61 \fBgit diff v1\&.0 v2\&.0 arch/x86 include/asm\-x86\fR,
62 \fBv1\&.0\fR
63 and
64 \fBv2\&.0\fR
65 are revisions and
66 \fBarch/x86\fR
67 and
68 \fBinclude/asm\-x86\fR
69 are paths\&.
70 .RE
71 .sp
72 .RS 4
73 .ie n \{\
74 \h'-04'\(bu\h'+03'\c
75 .\}
76 .el \{\
77 .sp -1
78 .IP \(bu 2.3
79 .\}
80 When an argument can be misunderstood as either a revision or a path, they can be disambiguated by placing
81 \fB\-\-\fR
82 between them\&. E\&.g\&.
83 \fBgit diff \-\- HEAD\fR
84 is, "I have a file called HEAD in my work tree\&. Please show changes between the version I staged in the index and what I have in the work tree for that file", not "show the difference between the HEAD commit and the work tree as a whole"\&. You can say
85 \fBgit diff HEAD \-\-\fR
86 to ask for the latter\&.
87 .RE
88 .sp
89 .RS 4
90 .ie n \{\
91 \h'-04'\(bu\h'+03'\c
92 .\}
93 .el \{\
94 .sp -1
95 .IP \(bu 2.3
96 .\}
97 Without disambiguating
98 \fB\-\-\fR, Git makes a reasonable guess, but errors out and asks you to disambiguate when ambiguous\&. E\&.g\&. if you have a file called HEAD in your work tree,
99 \fBgit diff HEAD\fR
100 is ambiguous, and you have to say either
101 \fBgit diff HEAD \-\-\fR
102 or
103 \fBgit diff \-\- HEAD\fR
104 to disambiguate\&.
105 .RE
106 .sp
107 .RS 4
108 .ie n \{\
109 \h'-04'\(bu\h'+03'\c
110 .\}
111 .el \{\
112 .sp -1
113 .IP \(bu 2.3
114 .\}
115 Because
116 \fB\-\-\fR
117 disambiguates revisions and paths in some commands, it cannot be used for those commands to separate options and revisions\&. You can use
118 \fB\-\-end\-of\-options\fR
119 for this (it also works for commands that do not distinguish between revisions in paths, in which case it is simply an alias for
120 \fB\-\-\fR)\&.
121 .sp
122 When writing a script that is expected to handle random user\-input, it is a good practice to make it explicit which arguments are which by placing disambiguating
123 \fB\-\-\fR
124 at appropriate places\&.
125 .RE
126 .sp
127 .RS 4
128 .ie n \{\
129 \h'-04'\(bu\h'+03'\c
130 .\}
131 .el \{\
132 .sp -1
133 .IP \(bu 2.3
134 .\}
135 Many commands allow wildcards in paths, but you need to protect them from getting globbed by the shell\&. These two mean different things:
136 .sp
137 .if n \{\
138 .RS 4
139 .\}
140 .nf
141 $ git restore *\&.c
142 $ git restore \e*\&.c
143 .fi
144 .if n \{\
145 .RE
146 .\}
147 .sp
148 The former lets your shell expand the fileglob, and you are asking the dot\-C files in your working tree to be overwritten with the version in the index\&. The latter passes the
149 \fB*\&.c\fR
150 to Git, and you are asking the paths in the index that match the pattern to be checked out to your working tree\&. After running
151 \fBgit add hello\&.c; rm hello\&.c\fR, you will
152 \fInot\fR
153 see
154 \fBhello\&.c\fR
155 in your working tree with the former, but with the latter you will\&.
156 .RE
157 .sp
158 .RS 4
159 .ie n \{\
160 \h'-04'\(bu\h'+03'\c
161 .\}
162 .el \{\
163 .sp -1
164 .IP \(bu 2.3
165 .\}
166 Just as the filesystem
167 \fI\&.\fR
168 (period) refers to the current directory, using a
169 \fI\&.\fR
170 as a repository name in Git (a dot\-repository) is a relative path and means your current repository\&.
171 .RE
172 .sp
173 Here are the rules regarding the "flags" that you should follow when you are scripting Git:
174 .sp
175 .RS 4
176 .ie n \{\
177 \h'-04'\(bu\h'+03'\c
178 .\}
179 .el \{\
180 .sp -1
181 .IP \(bu 2.3
182 .\}
183 Splitting short options to separate words (prefer
184 \fBgit foo \-a \-b\fR
185 to
186 \fBgit foo \-ab\fR, the latter may not even work)\&.
187 .RE
188 .sp
189 .RS 4
190 .ie n \{\
191 \h'-04'\(bu\h'+03'\c
192 .\}
193 .el \{\
194 .sp -1
195 .IP \(bu 2.3
196 .\}
197 When a command\-line option takes an argument, use the
198 \fIstuck\fR
199 form\&. In other words, write
200 \fBgit foo \-oArg\fR
201 instead of
202 \fBgit foo \-o Arg\fR
203 for short options, and
204 \fBgit foo \-\-long\-opt=Arg\fR
205 instead of
206 \fBgit foo \-\-long\-opt Arg\fR
207 for long options\&. An option that takes optional option\-argument must be written in the
208 \fIstuck\fR
209 form\&.
210 .RE
211 .sp
212 .RS 4
213 .ie n \{\
214 \h'-04'\(bu\h'+03'\c
215 .\}
216 .el \{\
217 .sp -1
218 .IP \(bu 2.3
219 .\}
220 When you give a revision parameter to a command, make sure the parameter is not ambiguous with a name of a file in the work tree\&. E\&.g\&. do not write
221 \fBgit log \-1 HEAD\fR
222 but write
223 \fBgit log \-1 HEAD \-\-\fR; the former will not work if you happen to have a file called
224 \fBHEAD\fR
225 in the work tree\&.
226 .RE
227 .sp
228 .RS 4
229 .ie n \{\
230 \h'-04'\(bu\h'+03'\c
231 .\}
232 .el \{\
233 .sp -1
234 .IP \(bu 2.3
235 .\}
236 Many commands allow a long option
237 \fB\-\-option\fR
238 to be abbreviated only to their unique prefix (e\&.g\&. if there is no other option whose name begins with
239 \fBopt\fR, you may be able to spell
240 \fB\-\-opt\fR
241 to invoke the
242 \fB\-\-option\fR
243 flag), but you should fully spell them out when writing your scripts; later versions of Git may introduce a new option whose name shares the same prefix, e\&.g\&.
244 \fB\-\-optimize\fR, to make a short prefix that used to be unique no longer unique\&.
245 .RE
246 .SH "ENHANCED OPTION PARSER"
247 .sp
248 From the Git 1\&.5\&.4 series and further, many Git commands (not all of them at the time of the writing though) come with an enhanced option parser\&.
249 .sp
250 Here is a list of the facilities provided by this option parser\&.
251 .SS "Magic Options"
252 .sp
253 Commands which have the enhanced option parser activated all understand a couple of magic command\-line options:
254 .PP
255 \-h
256 .RS 4
257 gives a pretty printed usage of the command\&.
258 .sp
259 .if n \{\
260 .RS 4
261 .\}
262 .nf
263 $ git describe \-h
264 usage: git describe [<options>] <commit\-ish>*
265 or: git describe [<options>] \-\-dirty
267 \-\-contains find the tag that comes after the commit
268 \-\-debug debug search strategy on stderr
269 \-\-all use any ref
270 \-\-tags use any tag, even unannotated
271 \-\-long always use long format
272 \-\-abbrev[=<n>] use <n> digits to display SHA\-1s
273 .fi
274 .if n \{\
275 .RE
276 .\}
277 .sp
278 Note that some subcommand (e\&.g\&.
279 \fBgit grep\fR) may behave differently when there are things on the command line other than
280 \fB\-h\fR, but
281 \fBgit subcmd \-h\fR
282 without anything else on the command line is meant to consistently give the usage\&.
283 .RE
284 .PP
285 \-\-help\-all
286 .RS 4
287 Some Git commands take options that are only used for plumbing or that are deprecated, and such options are hidden from the default usage\&. This option gives the full list of options\&.
288 .RE
289 .SS "Negating options"
290 .sp
291 Options with long option names can be negated by prefixing \fB\-\-no\-\fR\&. For example, \fBgit branch\fR has the option \fB\-\-track\fR which is \fIon\fR by default\&. You can use \fB\-\-no\-track\fR to override that behaviour\&. The same goes for \fB\-\-color\fR and \fB\-\-no\-color\fR\&.
292 .SS "Aggregating short options"
293 .sp
294 Commands that support the enhanced option parser allow you to aggregate short options\&. This means that you can for example use \fBgit rm \-rf\fR or \fBgit clean \-fdx\fR\&.
295 .SS "Abbreviating long options"
296 .sp
297 Commands that support the enhanced option parser accepts unique prefix of a long option as if it is fully spelled out, but use this with a caution\&. For example, \fBgit commit \-\-amen\fR behaves as if you typed \fBgit commit \-\-amend\fR, but that is true only until a later version of Git introduces another option that shares the same prefix, e\&.g\&. \fBgit commit \-\-amenity\fR option\&.
298 .SS "Separating argument from the option"
299 .sp
300 You can write the mandatory option parameter to an option as a separate word on the command line\&. That means that all the following uses work:
301 .sp
302 .if n \{\
303 .RS 4
304 .\}
305 .nf
306 $ git foo \-\-long\-opt=Arg
307 $ git foo \-\-long\-opt Arg
308 $ git foo \-oArg
309 $ git foo \-o Arg
310 .fi
311 .if n \{\
312 .RE
313 .\}
314 .sp
315 However, this is \fBNOT\fR allowed for switches with an optional value, where the \fIstuck\fR form must be used:
316 .sp
317 .if n \{\
318 .RS 4
319 .\}
320 .nf
321 $ git describe \-\-abbrev HEAD # correct
322 $ git describe \-\-abbrev=10 HEAD # correct
323 $ git describe \-\-abbrev 10 HEAD # NOT WHAT YOU MEANT
324 .fi
325 .if n \{\
326 .RE
327 .\}
328 .SH "NOTES ON FREQUENTLY CONFUSED OPTIONS"
329 .sp
330 Many commands that can work on files in the working tree and/or in the index can take \fB\-\-cached\fR and/or \fB\-\-index\fR options\&. Sometimes people incorrectly think that, because the index was originally called cache, these two are synonyms\&. They are \fBnot\fR \(em these two options mean very different things\&.
331 .sp
332 .RS 4
333 .ie n \{\
334 \h'-04'\(bu\h'+03'\c
335 .\}
336 .el \{\
337 .sp -1
338 .IP \(bu 2.3
339 .\}
340 The
341 \fB\-\-cached\fR
342 option is used to ask a command that usually works on files in the working tree to
343 \fBonly\fR
344 work with the index\&. For example,
345 \fBgit grep\fR, when used without a commit to specify from which commit to look for strings in, usually works on files in the working tree, but with the
346 \fB\-\-cached\fR
347 option, it looks for strings in the index\&.
348 .RE
349 .sp
350 .RS 4
351 .ie n \{\
352 \h'-04'\(bu\h'+03'\c
353 .\}
354 .el \{\
355 .sp -1
356 .IP \(bu 2.3
357 .\}
358 The
359 \fB\-\-index\fR
360 option is used to ask a command that usually works on files in the working tree to
361 \fBalso\fR
362 affect the index\&. For example,
363 \fBgit stash apply\fR
364 usually merges changes recorded in a stash entry to the working tree, but with the
365 \fB\-\-index\fR
366 option, it also merges changes to the index as well\&.
367 .RE
368 .sp
369 \fBgit apply\fR command can be used with \fB\-\-cached\fR and \fB\-\-index\fR (but not at the same time)\&. Usually the command only affects the files in the working tree, but with \fB\-\-index\fR, it patches both the files and their index entries, and with \fB\-\-cached\fR, it modifies only the index entries\&.
370 .sp
371 See also \m[blue]\fBhttps://lore\&.kernel\&.org/git/7v64clg5u9\&.fsf@assigned\-by\-dhcp\&.cox\&.net/\fR\m[] and \m[blue]\fBhttps://lore\&.kernel\&.org/git/7vy7ej9g38\&.fsf@gitster\&.siamese\&.dyndns\&.org/\fR\m[] for further information\&.
372 .sp
373 Some other commands that also work on files in the working tree and/or in the index can take \fB\-\-staged\fR and/or \fB\-\-worktree\fR\&.
374 .sp
375 .RS 4
376 .ie n \{\
377 \h'-04'\(bu\h'+03'\c
378 .\}
379 .el \{\
380 .sp -1
381 .IP \(bu 2.3
382 .\}
383 \fB\-\-staged\fR
384 is exactly like
385 \fB\-\-cached\fR, which is used to ask a command to only work on the index, not the working tree\&.
386 .RE
387 .sp
388 .RS 4
389 .ie n \{\
390 \h'-04'\(bu\h'+03'\c
391 .\}
392 .el \{\
393 .sp -1
394 .IP \(bu 2.3
395 .\}
396 \fB\-\-worktree\fR
397 is the opposite, to ask a command to work on the working tree only, not the index\&.
398 .RE
399 .sp
400 .RS 4
401 .ie n \{\
402 \h'-04'\(bu\h'+03'\c
403 .\}
404 .el \{\
405 .sp -1
406 .IP \(bu 2.3
407 .\}
408 The two options can be specified together to ask a command to work on both the index and the working tree\&.
409 .RE
410 .SH "GIT"
411 .sp
412 Part of the \fBgit\fR(1) suite