| blob | a48cf7bc04762692597e109a2003bc0129d90c98 |
1 '\" t
2 .\" Title: gitcli
3 .\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
5 .\" Date: 2023-06-01
6 .\" Manual: Git Manual
7 .\" Source: Git 2.41.0
8 .\" Language: English
9 .\"
10 .TH "GITCLI" "7" "2023\-06\-01" "Git 2\&.41\&.0" "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 gave 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 ambiguity 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 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 asking 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 It\(cqs preferred to use the non\-dashed form of Git commands, which means that you should prefer
184 \fBgit foo\fR
185 to
186 \fBgit\-foo\fR\&.
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 Splitting short options to separate words (prefer
198 \fBgit foo \-a \-b\fR
199 to
200 \fBgit foo \-ab\fR, the latter may not even work)\&.
201 .RE
202 .sp
203 .RS 4
204 .ie n \{\
205 \h'-04'\(bu\h'+03'\c
206 .\}
207 .el \{\
208 .sp -1
209 .IP \(bu 2.3
210 .\}
211 When a command\-line option takes an argument, use the
212 \fIstuck\fR
213 form\&. In other words, write
214 \fBgit foo \-oArg\fR
215 instead of
216 \fBgit foo \-o Arg\fR
217 for short options, and
218 \fBgit foo \-\-long\-opt=Arg\fR
219 instead of
220 \fBgit foo \-\-long\-opt Arg\fR
221 for long options\&. An option that takes optional option\-argument must be written in the
222 \fIstuck\fR
223 form\&.
224 .RE
225 .sp
226 .RS 4
227 .ie n \{\
228 \h'-04'\(bu\h'+03'\c
229 .\}
230 .el \{\
231 .sp -1
232 .IP \(bu 2.3
233 .\}
234 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
235 \fBgit log \-1 HEAD\fR
236 but write
237 \fBgit log \-1 HEAD \-\-\fR; the former will not work if you happen to have a file called
238 \fBHEAD\fR
239 in the work tree\&.
240 .RE
241 .sp
242 .RS 4
243 .ie n \{\
244 \h'-04'\(bu\h'+03'\c
245 .\}
246 .el \{\
247 .sp -1
248 .IP \(bu 2.3
249 .\}
250 Many commands allow a long option
251 \fB\-\-option\fR
252 to be abbreviated only to their unique prefix (e\&.g\&. if there is no other option whose name begins with
253 \fBopt\fR, you may be able to spell
254 \fB\-\-opt\fR
255 to invoke the
256 \fB\-\-option\fR
257 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\&.
258 \fB\-\-optimize\fR, to make a short prefix that used to be unique no longer unique\&.
259 .RE
260 .SH "ENHANCED OPTION PARSER"
261 .sp
262 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\&.
263 .sp
264 Here is a list of the facilities provided by this option parser\&.
265 .SS "Magic Options"
266 .sp
267 Commands which have the enhanced option parser activated all understand a couple of magic command\-line options:
268 .PP
269 \-h
270 .RS 4
271 gives a pretty printed usage of the command\&.
272 .sp
273 .if n \{\
274 .RS 4
275 .\}
276 .nf
277 $ git describe \-h
278 usage: git describe [<options>] <commit\-ish>*
279 or: git describe [<options>] \-\-dirty
281 \-\-contains find the tag that comes after the commit
282 \-\-debug debug search strategy on stderr
283 \-\-all use any ref
284 \-\-tags use any tag, even unannotated
285 \-\-long always use long format
286 \-\-abbrev[=<n>] use <n> digits to display SHA\-1s
287 .fi
288 .if n \{\
289 .RE
290 .\}
291 .sp
292 Note that some subcommand (e\&.g\&.
293 \fBgit grep\fR) may behave differently when there are things on the command line other than
294 \fB\-h\fR, but
295 \fBgit subcmd \-h\fR
296 without anything else on the command line is meant to consistently give the usage\&.
297 .RE
298 .PP
299 \-\-help\-all
300 .RS 4
301 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\&.
302 .RE
303 .SS "Negating options"
304 .sp
305 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\&.
306 .SS "Aggregating short options"
307 .sp
308 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\&.
309 .SS "Abbreviating long options"
310 .sp
311 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\&.
312 .SS "Separating argument from the option"
313 .sp
314 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:
315 .sp
316 .if n \{\
317 .RS 4
318 .\}
319 .nf
320 $ git foo \-\-long\-opt=Arg
321 $ git foo \-\-long\-opt Arg
322 $ git foo \-oArg
323 $ git foo \-o Arg
324 .fi
325 .if n \{\
326 .RE
327 .\}
328 .sp
329 .sp
330 However, this is \fBNOT\fR allowed for switches with an optional value, where the \fIstuck\fR form must be used:
331 .sp
332 .if n \{\
333 .RS 4
334 .\}
335 .nf
336 $ git describe \-\-abbrev HEAD # correct
337 $ git describe \-\-abbrev=10 HEAD # correct
338 $ git describe \-\-abbrev 10 HEAD # NOT WHAT YOU MEANT
339 .fi
340 .if n \{\
341 .RE
342 .\}
343 .sp
344 .SH "NOTES ON FREQUENTLY CONFUSED OPTIONS"
345 .sp
346 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\&.
347 .sp
348 .RS 4
349 .ie n \{\
350 \h'-04'\(bu\h'+03'\c
351 .\}
352 .el \{\
353 .sp -1
354 .IP \(bu 2.3
355 .\}
356 The
357 \fB\-\-cached\fR
358 option is used to ask a command that usually works on files in the working tree to
359 \fBonly\fR
360 work with the index\&. For example,
361 \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
362 \fB\-\-cached\fR
363 option, it looks for strings in the index\&.
364 .RE
365 .sp
366 .RS 4
367 .ie n \{\
368 \h'-04'\(bu\h'+03'\c
369 .\}
370 .el \{\
371 .sp -1
372 .IP \(bu 2.3
373 .\}
374 The
375 \fB\-\-index\fR
376 option is used to ask a command that usually works on files in the working tree to
377 \fBalso\fR
378 affect the index\&. For example,
379 \fBgit stash apply\fR
380 usually merges changes recorded in a stash entry to the working tree, but with the
381 \fB\-\-index\fR
382 option, it also merges changes to the index as well\&.
383 .RE
384 .sp
385 \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\&.
386 .sp
387 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\&.
388 .sp
389 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\&.
390 .sp
391 .RS 4
392 .ie n \{\
393 \h'-04'\(bu\h'+03'\c
394 .\}
395 .el \{\
396 .sp -1
397 .IP \(bu 2.3
398 .\}
399 \fB\-\-staged\fR
400 is exactly like
401 \fB\-\-cached\fR, which is used to ask a command to only work on the index, not the working tree\&.
402 .RE
403 .sp
404 .RS 4
405 .ie n \{\
406 \h'-04'\(bu\h'+03'\c
407 .\}
408 .el \{\
409 .sp -1
410 .IP \(bu 2.3
411 .\}
412 \fB\-\-worktree\fR
413 is the opposite, to ask a command to work on the working tree only, not the index\&.
414 .RE
415 .sp
416 .RS 4
417 .ie n \{\
418 \h'-04'\(bu\h'+03'\c
419 .\}
420 .el \{\
421 .sp -1
422 .IP \(bu 2.3
423 .\}
424 The two options can be specified together to ask a command to work on both the index and the working tree\&.
425 .RE
426 .SH "GIT"
427 .sp
428 Part of the \fBgit\fR(1) suite