logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

gitcli.7 (14181B)


  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: 2025-03-14
  6. .\" Manual: Git Manual
  7. .\" Source: Git 2.49.0
  8. .\" Language: English
  9. .\"
  10. .TH "GITCLI" "7" "2025-03-14" "Git 2\&.49\&.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 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\&.
  258. \fB~/directory/file\fR
  259. or
  260. \fB~u/d/f\fR, you may want to use the separate form, e\&.g\&.
  261. \fBgit\fR
  262. \fBfoo\fR
  263. \fB\-\-file\fR
  264. \fB~/mine\fR, not
  265. \fBgit\fR
  266. \fBfoo\fR
  267. \fB\-\-file=~/mine\fR\&. The shell will expand
  268. \fB~/\fR
  269. 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\&.
  270. .RE
  271. .sp
  272. .RS 4
  273. .ie n \{\
  274. \h'-04'\(bu\h'+03'\c
  275. .\}
  276. .el \{\
  277. .sp -1
  278. .IP \(bu 2.3
  279. .\}
  280. 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
  281. \fBgit\fR
  282. \fBlog\fR
  283. \fB\-1\fR
  284. \fBHEAD\fR
  285. but write
  286. \fBgit\fR
  287. \fBlog\fR
  288. \fB\-1\fR
  289. \fBHEAD\fR
  290. \fB\-\-\fR; the former will not work if you happen to have a file called
  291. \fBHEAD\fR
  292. in the work tree\&.
  293. .RE
  294. .sp
  295. .RS 4
  296. .ie n \{\
  297. \h'-04'\(bu\h'+03'\c
  298. .\}
  299. .el \{\
  300. .sp -1
  301. .IP \(bu 2.3
  302. .\}
  303. Many commands allow a long option
  304. \fB\-\-option\fR
  305. to be abbreviated only to their unique prefix (e\&.g\&. if there is no other option whose name begins with
  306. \fBopt\fR, you may be able to spell
  307. \fB\-\-opt\fR
  308. to invoke the
  309. \fB\-\-option\fR
  310. 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\&.
  311. \fB\-\-optimize\fR, to make a short prefix that used to be unique no longer unique\&.
  312. .RE
  313. .SH "ENHANCED OPTION PARSER"
  314. .sp
  315. 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\&.
  316. .sp
  317. Here is a list of the facilities provided by this option parser\&.
  318. .SS "Magic Options"
  319. .sp
  320. Commands which have the enhanced option parser activated all understand a couple of magic command\-line options:
  321. .PP
  322. \-h
  323. .RS 4
  324. gives a pretty printed usage of the command\&.
  325. .sp
  326. .if n \{\
  327. .RS 4
  328. .\}
  329. .nf
  330. $ git describe \-h
  331. usage: git describe [<options>] <commit\-ish>*
  332. or: git describe [<options>] \-\-dirty
  333. \-\-contains find the tag that comes after the commit
  334. \-\-debug debug search strategy on stderr
  335. \-\-all use any ref
  336. \-\-tags use any tag, even unannotated
  337. \-\-long always use long format
  338. \-\-abbrev[=<n>] use <n> digits to display SHA\-1s
  339. .fi
  340. .if n \{\
  341. .RE
  342. .\}
  343. .sp
  344. Note that some subcommand (e\&.g\&.
  345. \fBgit\fR
  346. \fBgrep\fR) may behave differently when there are things on the command line other than
  347. \fB\-h\fR, but
  348. \fBgit\fR
  349. \fBsubcmd\fR
  350. \fB\-h\fR
  351. without anything else on the command line is meant to consistently give the usage\&.
  352. .RE
  353. .PP
  354. \-\-help\-all
  355. .RS 4
  356. 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\&.
  357. .RE
  358. .SS "Negating options"
  359. .sp
  360. 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\&.
  361. .SS "Options trump configuration and environment"
  362. .sp
  363. When there is a configuration variable or an environment variable that tweak the behaviour of an aspect of a Git command, and also a command line option that tweaks the same, the command line option overrides what the configuration and/or environment variable say\&.
  364. .sp
  365. For example, the \fBuser\&.name\fR configuration variable is used to specify the human\-readable name used by the \fBgit\fR \fBcommit\fR command to record the author and the committer name in a newly created commit\&. The \fBGIT_AUTHOR_NAME\fR environment variable, if set, takes precedence when deciding what author name to record\&. The \fB\-\-author=\fR\fI<author>\fR command line option of the \fBgit\fR \fBcommit\fR command, when given, takes precedence over these two sources of information\&.
  366. .SS "Aggregating short options"
  367. .sp
  368. 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\&.
  369. .SS "Abbreviating long options"
  370. .sp
  371. 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\&.
  372. .SS "Separating argument from the option"
  373. .sp
  374. 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:
  375. .sp
  376. .if n \{\
  377. .RS 4
  378. .\}
  379. .nf
  380. $ git foo \-\-long\-opt=Arg
  381. $ git foo \-\-long\-opt Arg
  382. $ git foo \-oArg
  383. $ git foo \-o Arg
  384. .fi
  385. .if n \{\
  386. .RE
  387. .\}
  388. .sp
  389. However, this is \fBNOT\fR allowed for switches with an optional value, where the \fIstuck\fR form must be used:
  390. .sp
  391. .if n \{\
  392. .RS 4
  393. .\}
  394. .nf
  395. $ git describe \-\-abbrev HEAD # correct
  396. $ git describe \-\-abbrev=10 HEAD # correct
  397. $ git describe \-\-abbrev 10 HEAD # NOT WHAT YOU MEANT
  398. .fi
  399. .if n \{\
  400. .RE
  401. .\}
  402. .SH "NOTES ON FREQUENTLY CONFUSED OPTIONS"
  403. .sp
  404. 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\&.
  405. .sp
  406. .RS 4
  407. .ie n \{\
  408. \h'-04'\(bu\h'+03'\c
  409. .\}
  410. .el \{\
  411. .sp -1
  412. .IP \(bu 2.3
  413. .\}
  414. The
  415. \fB\-\-cached\fR
  416. option is used to ask a command that usually works on files in the working tree to
  417. \fBonly\fR
  418. work with the index\&. For example,
  419. \fBgit\fR
  420. \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
  421. \fB\-\-cached\fR
  422. option, it looks for strings in the index\&.
  423. .RE
  424. .sp
  425. .RS 4
  426. .ie n \{\
  427. \h'-04'\(bu\h'+03'\c
  428. .\}
  429. .el \{\
  430. .sp -1
  431. .IP \(bu 2.3
  432. .\}
  433. The
  434. \fB\-\-index\fR
  435. option is used to ask a command that usually works on files in the working tree to
  436. \fBalso\fR
  437. affect the index\&. For example,
  438. \fBgit\fR
  439. \fBstash\fR
  440. \fBapply\fR
  441. usually merges changes recorded in a stash entry to the working tree, but with the
  442. \fB\-\-index\fR
  443. option, it also merges changes to the index as well\&.
  444. .RE
  445. .sp
  446. \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\&.
  447. .sp
  448. 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\&.
  449. .sp
  450. 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\&.
  451. .sp
  452. .RS 4
  453. .ie n \{\
  454. \h'-04'\(bu\h'+03'\c
  455. .\}
  456. .el \{\
  457. .sp -1
  458. .IP \(bu 2.3
  459. .\}
  460. \fB\-\-staged\fR
  461. is exactly like
  462. \fB\-\-cached\fR, which is used to ask a command to only work on the index, not the working tree\&.
  463. .RE
  464. .sp
  465. .RS 4
  466. .ie n \{\
  467. \h'-04'\(bu\h'+03'\c
  468. .\}
  469. .el \{\
  470. .sp -1
  471. .IP \(bu 2.3
  472. .\}
  473. \fB\-\-worktree\fR
  474. is the opposite, to ask a command to work on the working tree only, not the index\&.
  475. .RE
  476. .sp
  477. .RS 4
  478. .ie n \{\
  479. \h'-04'\(bu\h'+03'\c
  480. .\}
  481. .el \{\
  482. .sp -1
  483. .IP \(bu 2.3
  484. .\}
  485. The two options can be specified together to ask a command to work on both the index and the working tree\&.
  486. .RE
  487. .SH "GIT"
  488. .sp
  489. Part of the \fBgit\fR(1) suite