man7/gitcli.7

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