| blob | a006bb2fe4731496da1e2dc6ffac3c45b9d25fb0 |
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: 12/10/2021
6 .\" Manual: Git Manual
7 .\" Source: Git 2.34.1.182.ge773545c7f
8 .\" Language: English
9 .\"
10 .TH "GITCLI" "7" "12/10/2021" "Git 2\&.34\&.1\&.182\&.ge77354" "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 Revisions come first and then paths\&. E\&.g\&. in
50 \fBgit diff v1\&.0 v2\&.0 arch/x86 include/asm\-x86\fR,
51 \fBv1\&.0\fR
52 and
53 \fBv2\&.0\fR
54 are revisions and
55 \fBarch/x86\fR
56 and
57 \fBinclude/asm\-x86\fR
58 are paths\&.
59 .RE
60 .sp
61 .RS 4
62 .ie n \{\
63 \h'-04'\(bu\h'+03'\c
64 .\}
65 .el \{\
66 .sp -1
67 .IP \(bu 2.3
68 .\}
69 When an argument can be misunderstood as either a revision or a path, they can be disambiguated by placing
70 \fB\-\-\fR
71 between them\&. E\&.g\&.
72 \fBgit diff \-\- HEAD\fR
73 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
74 \fBgit diff HEAD \-\-\fR
75 to ask for the latter\&.
76 .RE
77 .sp
78 .RS 4
79 .ie n \{\
80 \h'-04'\(bu\h'+03'\c
81 .\}
82 .el \{\
83 .sp -1
84 .IP \(bu 2.3
85 .\}
86 Without disambiguating
87 \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,
88 \fBgit diff HEAD\fR
89 is ambiguous, and you have to say either
90 \fBgit diff HEAD \-\-\fR
91 or
92 \fBgit diff \-\- HEAD\fR
93 to disambiguate\&.
94 .RE
95 .sp
96 .RS 4
97 .ie n \{\
98 \h'-04'\(bu\h'+03'\c
99 .\}
100 .el \{\
101 .sp -1
102 .IP \(bu 2.3
103 .\}
104 Because
105 \fB\-\-\fR
106 disambiguates revisions and paths in some commands, it cannot be used for those commands to separate options and revisions\&. You can use
107 \fB\-\-end\-of\-options\fR
108 for this (it also works for commands that do not distinguish between revisions in paths, in which case it is simply an alias for
109 \fB\-\-\fR)\&.
110 .sp
111 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
112 \fB\-\-\fR
113 at appropriate places\&.
114 .RE
115 .sp
116 .RS 4
117 .ie n \{\
118 \h'-04'\(bu\h'+03'\c
119 .\}
120 .el \{\
121 .sp -1
122 .IP \(bu 2.3
123 .\}
124 Many commands allow wildcards in paths, but you need to protect them from getting globbed by the shell\&. These two mean different things:
125 .sp
126 .if n \{\
127 .RS 4
128 .\}
129 .nf
130 $ git restore *\&.c
131 $ git restore \e*\&.c
132 .fi
133 .if n \{\
134 .RE
135 .\}
136 .sp
137 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
138 \fB*\&.c\fR
139 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
140 \fBgit add hello\&.c; rm hello\&.c\fR, you will
141 \fInot\fR
142 see
143 \fBhello\&.c\fR
144 in your working tree with the former, but with the latter you will\&.
145 .RE
146 .sp
147 .RS 4
148 .ie n \{\
149 \h'-04'\(bu\h'+03'\c
150 .\}
151 .el \{\
152 .sp -1
153 .IP \(bu 2.3
154 .\}
155 Just as the filesystem
156 \fI\&.\fR
157 (period) refers to the current directory, using a
158 \fI\&.\fR
159 as a repository name in Git (a dot\-repository) is a relative path and means your current repository\&.
160 .RE
161 .sp
162 Here are the rules regarding the "flags" that you should follow when you are scripting Git:
163 .sp
164 .RS 4
165 .ie n \{\
166 \h'-04'\(bu\h'+03'\c
167 .\}
168 .el \{\
169 .sp -1
170 .IP \(bu 2.3
171 .\}
172 it\(cqs preferred to use the non\-dashed form of Git commands, which means that you should prefer
173 \fBgit foo\fR
174 to
175 \fBgit\-foo\fR\&.
176 .RE
177 .sp
178 .RS 4
179 .ie n \{\
180 \h'-04'\(bu\h'+03'\c
181 .\}
182 .el \{\
183 .sp -1
184 .IP \(bu 2.3
185 .\}
186 splitting short options to separate words (prefer
187 \fBgit foo \-a \-b\fR
188 to
189 \fBgit foo \-ab\fR, the latter may not even work)\&.
190 .RE
191 .sp
192 .RS 4
193 .ie n \{\
194 \h'-04'\(bu\h'+03'\c
195 .\}
196 .el \{\
197 .sp -1
198 .IP \(bu 2.3
199 .\}
200 when a command\-line option takes an argument, use the
201 \fIstuck\fR
202 form\&. In other words, write
203 \fBgit foo \-oArg\fR
204 instead of
205 \fBgit foo \-o Arg\fR
206 for short options, and
207 \fBgit foo \-\-long\-opt=Arg\fR
208 instead of
209 \fBgit foo \-\-long\-opt Arg\fR
210 for long options\&. An option that takes optional option\-argument must be written in the
211 \fIstuck\fR
212 form\&.
213 .RE
214 .sp
215 .RS 4
216 .ie n \{\
217 \h'-04'\(bu\h'+03'\c
218 .\}
219 .el \{\
220 .sp -1
221 .IP \(bu 2.3
222 .\}
223 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
224 \fBgit log \-1 HEAD\fR
225 but write
226 \fBgit log \-1 HEAD \-\-\fR; the former will not work if you happen to have a file called
227 \fBHEAD\fR
228 in the work tree\&.
229 .RE
230 .sp
231 .RS 4
232 .ie n \{\
233 \h'-04'\(bu\h'+03'\c
234 .\}
235 .el \{\
236 .sp -1
237 .IP \(bu 2.3
238 .\}
239 many commands allow a long option
240 \fB\-\-option\fR
241 to be abbreviated only to their unique prefix (e\&.g\&. if there is no other option whose name begins with
242 \fBopt\fR, you may be able to spell
243 \fB\-\-opt\fR
244 to invoke the
245 \fB\-\-option\fR
246 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\&.
247 \fB\-\-optimize\fR, to make a short prefix that used to be unique no longer unique\&.
248 .RE
249 .SH "ENHANCED OPTION PARSER"
250 .sp
251 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\&.
252 .sp
253 Here is a list of the facilities provided by this option parser\&.
254 .SS "Magic Options"
255 .sp
256 Commands which have the enhanced option parser activated all understand a couple of magic command\-line options:
257 .PP
258 \-h
259 .RS 4
260 gives a pretty printed usage of the command\&.
261 .sp
262 .if n \{\
263 .RS 4
264 .\}
265 .nf
266 $ git describe \-h
267 usage: git describe [<options>] <commit\-ish>*
268 or: git describe [<options>] \-\-dirty
270 \-\-contains find the tag that comes after the commit
271 \-\-debug debug search strategy on stderr
272 \-\-all use any ref
273 \-\-tags use any tag, even unannotated
274 \-\-long always use long format
275 \-\-abbrev[=<n>] use <n> digits to display SHA\-1s
276 .fi
277 .if n \{\
278 .RE
279 .\}
280 .sp
281 Note that some subcommand (e\&.g\&.
282 \fBgit grep\fR) may behave differently when there are things on the command line other than
283 \fB\-h\fR, but
284 \fBgit subcmd \-h\fR
285 without anything else on the command line is meant to consistently give the usage\&.
286 .RE
287 .PP
288 \-\-help\-all
289 .RS 4
290 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\&.
291 .RE
292 .SS "Negating options"
293 .sp
294 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\&.
295 .SS "Aggregating short options"
296 .sp
297 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\&.
298 .SS "Abbreviating long options"
299 .sp
300 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\&.
301 .SS "Separating argument from the option"
302 .sp
303 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:
304 .sp
305 .if n \{\
306 .RS 4
307 .\}
308 .nf
309 $ git foo \-\-long\-opt=Arg
310 $ git foo \-\-long\-opt Arg
311 $ git foo \-oArg
312 $ git foo \-o Arg
313 .fi
314 .if n \{\
315 .RE
316 .\}
317 .sp
318 .sp
319 However, this is \fBNOT\fR allowed for switches with an optional value, where the \fIstuck\fR form must be used:
320 .sp
321 .if n \{\
322 .RS 4
323 .\}
324 .nf
325 $ git describe \-\-abbrev HEAD # correct
326 $ git describe \-\-abbrev=10 HEAD # correct
327 $ git describe \-\-abbrev 10 HEAD # NOT WHAT YOU MEANT
328 .fi
329 .if n \{\
330 .RE
331 .\}
332 .sp
333 .SH "NOTES ON FREQUENTLY CONFUSED OPTIONS"
334 .sp
335 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\&.
336 .sp
337 .RS 4
338 .ie n \{\
339 \h'-04'\(bu\h'+03'\c
340 .\}
341 .el \{\
342 .sp -1
343 .IP \(bu 2.3
344 .\}
345 The
346 \fB\-\-cached\fR
347 option is used to ask a command that usually works on files in the working tree to
348 \fBonly\fR
349 work with the index\&. For example,
350 \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
351 \fB\-\-cached\fR
352 option, it looks for strings in the index\&.
353 .RE
354 .sp
355 .RS 4
356 .ie n \{\
357 \h'-04'\(bu\h'+03'\c
358 .\}
359 .el \{\
360 .sp -1
361 .IP \(bu 2.3
362 .\}
363 The
364 \fB\-\-index\fR
365 option is used to ask a command that usually works on files in the working tree to
366 \fBalso\fR
367 affect the index\&. For example,
368 \fBgit stash apply\fR
369 usually merges changes recorded in a stash entry to the working tree, but with the
370 \fB\-\-index\fR
371 option, it also merges changes to the index as well\&.
372 .RE
373 .sp
374 \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\&.
375 .sp
376 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\&.
377 .sp
378 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\&.
379 .sp
380 .RS 4
381 .ie n \{\
382 \h'-04'\(bu\h'+03'\c
383 .\}
384 .el \{\
385 .sp -1
386 .IP \(bu 2.3
387 .\}
388 \fB\-\-staged\fR
389 is exactly like
390 \fB\-\-cached\fR, which is used to ask a command to only work on the index, not the working tree\&.
391 .RE
392 .sp
393 .RS 4
394 .ie n \{\
395 \h'-04'\(bu\h'+03'\c
396 .\}
397 .el \{\
398 .sp -1
399 .IP \(bu 2.3
400 .\}
401 \fB\-\-worktree\fR
402 is the opposite, to ask a command to work on the working tree only, not the index\&.
403 .RE
404 .sp
405 .RS 4
406 .ie n \{\
407 \h'-04'\(bu\h'+03'\c
408 .\}
409 .el \{\
410 .sp -1
411 .IP \(bu 2.3
412 .\}
413 The two options can be specified together to ask a command to work on both the index and the working tree\&.
414 .RE
415 .SH "GIT"
416 .sp
417 Part of the \fBgit\fR(1) suite