gitcli.7 (14181B)
- '\" t
- .\" Title: gitcli
- .\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
- .\" Generator: DocBook XSL Stylesheets v1.79.2 <http://docbook.sf.net/>
- .\" Date: 2025-03-14
- .\" Manual: Git Manual
- .\" Source: Git 2.49.0
- .\" Language: English
- .\"
- .TH "GITCLI" "7" "2025-03-14" "Git 2\&.49\&.0" "Git Manual"
- .\" -----------------------------------------------------------------
- .\" * Define some portability stuff
- .\" -----------------------------------------------------------------
- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- .\" http://bugs.debian.org/507673
- .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- .ie \n(.g .ds Aq \(aq
- .el .ds Aq '
- .\" -----------------------------------------------------------------
- .\" * set default formatting
- .\" -----------------------------------------------------------------
- .\" disable hyphenation
- .nh
- .\" disable justification (adjust text to left margin only)
- .ad l
- .\" -----------------------------------------------------------------
- .\" * MAIN CONTENT STARTS HERE *
- .\" -----------------------------------------------------------------
- .SH "NAME"
- gitcli \- Git command\-line interface and conventions
- .SH "SYNOPSIS"
- .sp
- gitcli
- .SH "DESCRIPTION"
- .sp
- This manual describes the convention used throughout Git CLI\&.
- .sp
- 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:
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- 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)\&.
- .RE
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- Revisions come first and then paths\&. E\&.g\&. in
- \fBgit\fR
- \fBdiff\fR
- \fBv1\&.0\fR
- \fBv2\&.0\fR
- \fBarch/x86\fR
- \fBinclude/asm\-x86\fR,
- \fBv1\&.0\fR
- and
- \fBv2\&.0\fR
- are revisions and
- \fBarch/x86\fR
- and
- \fBinclude/asm\-x86\fR
- are paths\&.
- .RE
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- When an argument can be misunderstood as either a revision or a path, they can be disambiguated by placing
- \fB\-\-\fR
- between them\&. E\&.g\&.
- \fBgit\fR
- \fBdiff\fR
- \fB\-\-\fR
- \fBHEAD\fR
- 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
- \fBgit\fR
- \fBdiff\fR
- \fBHEAD\fR
- \fB\-\-\fR
- to ask for the latter\&.
- .RE
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- Without disambiguating
- \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,
- \fBgit\fR
- \fBdiff\fR
- \fBHEAD\fR
- is ambiguous, and you have to say either
- \fBgit\fR
- \fBdiff\fR
- \fBHEAD\fR
- \fB\-\-\fR
- or
- \fBgit\fR
- \fBdiff\fR
- \fB\-\-\fR
- \fBHEAD\fR
- to disambiguate\&.
- .RE
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- Because
- \fB\-\-\fR
- disambiguates revisions and paths in some commands, it cannot be used for those commands to separate options and revisions\&. You can use
- \fB\-\-end\-of\-options\fR
- for this (it also works for commands that do not distinguish between revisions in paths, in which case it is simply an alias for
- \fB\-\-\fR)\&.
- .sp
- 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
- \fB\-\-\fR
- at appropriate places\&.
- .RE
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- Many commands allow wildcards in paths, but you need to protect them from getting globbed by the shell\&. These two mean different things:
- .sp
- .if n \{\
- .RS 4
- .\}
- .nf
- $ git restore *\&.c
- $ git restore \e*\&.c
- .fi
- .if n \{\
- .RE
- .\}
- .sp
- 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
- 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
- \fBgit\fR
- \fBadd\fR
- \fBhello\&.c\fR;
- \fBrm\fR
- \fBhello\&.c\fR, you will
- \fInot\fR
- see
- \fBhello\&.c\fR
- in your working tree with the former, but with the latter you will\&.
- .RE
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- Just as the filesystem
- \fI\&.\fR
- (period) refers to the current directory, using a
- \fI\&.\fR
- as a repository name in Git (a dot\-repository) is a relative path and means your current repository\&.
- .RE
- .sp
- Here are the rules regarding the "flags" that you should follow when you are scripting Git:
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- Splitting short options to separate words (prefer
- \fBgit\fR
- \fBfoo\fR
- \fB\-a\fR
- \fB\-b\fR
- to
- \fBgit\fR
- \fBfoo\fR
- \fB\-ab\fR, the latter may not even work)\&.
- .RE
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- When a command\-line option takes an argument, use the
- \fIstuck\fR
- form\&. In other words, write
- \fBgit\fR
- \fBfoo\fR
- \fB\-oArg\fR
- instead of
- \fBgit\fR
- \fBfoo\fR
- \fB\-o\fR
- \fBArg\fR
- for short options, and
- \fBgit\fR
- \fBfoo\fR
- \fB\-\-long\-opt=Arg\fR
- instead of
- \fBgit\fR
- \fBfoo\fR
- \fB\-\-long\-opt\fR
- \fBArg\fR
- for long options\&. An option that takes optional option\-argument must be written in the
- \fIstuck\fR
- form\&.
- .RE
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- Despite the above suggestion, when Arg is a path relative to the home directory of a user, e\&.g\&.
- \fB~/directory/file\fR
- or
- \fB~u/d/f\fR, you may want to use the separate form, e\&.g\&.
- \fBgit\fR
- \fBfoo\fR
- \fB\-\-file\fR
- \fB~/mine\fR, not
- \fBgit\fR
- \fBfoo\fR
- \fB\-\-file=~/mine\fR\&. The shell will expand
- \fB~/\fR
- 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\&.
- .RE
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- 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
- \fBgit\fR
- \fBlog\fR
- \fB\-1\fR
- \fBHEAD\fR
- but write
- \fBgit\fR
- \fBlog\fR
- \fB\-1\fR
- \fBHEAD\fR
- \fB\-\-\fR; the former will not work if you happen to have a file called
- \fBHEAD\fR
- in the work tree\&.
- .RE
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- Many commands allow a long option
- \fB\-\-option\fR
- to be abbreviated only to their unique prefix (e\&.g\&. if there is no other option whose name begins with
- \fBopt\fR, you may be able to spell
- \fB\-\-opt\fR
- to invoke the
- \fB\-\-option\fR
- 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\&.
- \fB\-\-optimize\fR, to make a short prefix that used to be unique no longer unique\&.
- .RE
- .SH "ENHANCED OPTION PARSER"
- .sp
- 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\&.
- .sp
- Here is a list of the facilities provided by this option parser\&.
- .SS "Magic Options"
- .sp
- Commands which have the enhanced option parser activated all understand a couple of magic command\-line options:
- .PP
- \-h
- .RS 4
- gives a pretty printed usage of the command\&.
- .sp
- .if n \{\
- .RS 4
- .\}
- .nf
- $ git describe \-h
- usage: git describe [<options>] <commit\-ish>*
- or: git describe [<options>] \-\-dirty
- \-\-contains find the tag that comes after the commit
- \-\-debug debug search strategy on stderr
- \-\-all use any ref
- \-\-tags use any tag, even unannotated
- \-\-long always use long format
- \-\-abbrev[=<n>] use <n> digits to display SHA\-1s
- .fi
- .if n \{\
- .RE
- .\}
- .sp
- Note that some subcommand (e\&.g\&.
- \fBgit\fR
- \fBgrep\fR) may behave differently when there are things on the command line other than
- \fB\-h\fR, but
- \fBgit\fR
- \fBsubcmd\fR
- \fB\-h\fR
- without anything else on the command line is meant to consistently give the usage\&.
- .RE
- .PP
- \-\-help\-all
- .RS 4
- 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\&.
- .RE
- .SS "Negating options"
- .sp
- 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\&.
- .SS "Options trump configuration and environment"
- .sp
- 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\&.
- .sp
- 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\&.
- .SS "Aggregating short options"
- .sp
- 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\&.
- .SS "Abbreviating long options"
- .sp
- 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\&.
- .SS "Separating argument from the option"
- .sp
- 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:
- .sp
- .if n \{\
- .RS 4
- .\}
- .nf
- $ git foo \-\-long\-opt=Arg
- $ git foo \-\-long\-opt Arg
- $ git foo \-oArg
- $ git foo \-o Arg
- .fi
- .if n \{\
- .RE
- .\}
- .sp
- However, this is \fBNOT\fR allowed for switches with an optional value, where the \fIstuck\fR form must be used:
- .sp
- .if n \{\
- .RS 4
- .\}
- .nf
- $ git describe \-\-abbrev HEAD # correct
- $ git describe \-\-abbrev=10 HEAD # correct
- $ git describe \-\-abbrev 10 HEAD # NOT WHAT YOU MEANT
- .fi
- .if n \{\
- .RE
- .\}
- .SH "NOTES ON FREQUENTLY CONFUSED OPTIONS"
- .sp
- 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\&.
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- The
- \fB\-\-cached\fR
- option is used to ask a command that usually works on files in the working tree to
- \fBonly\fR
- work with the index\&. For example,
- \fBgit\fR
- \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
- \fB\-\-cached\fR
- option, it looks for strings in the index\&.
- .RE
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- The
- \fB\-\-index\fR
- option is used to ask a command that usually works on files in the working tree to
- \fBalso\fR
- affect the index\&. For example,
- \fBgit\fR
- \fBstash\fR
- \fBapply\fR
- usually merges changes recorded in a stash entry to the working tree, but with the
- \fB\-\-index\fR
- option, it also merges changes to the index as well\&.
- .RE
- .sp
- \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\&.
- .sp
- 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\&.
- .sp
- 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\&.
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- \fB\-\-staged\fR
- is exactly like
- \fB\-\-cached\fR, which is used to ask a command to only work on the index, not the working tree\&.
- .RE
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- \fB\-\-worktree\fR
- is the opposite, to ask a command to work on the working tree only, not the index\&.
- .RE
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- The two options can be specified together to ask a command to work on both the index and the working tree\&.
- .RE
- .SH "GIT"
- .sp
- Part of the \fBgit\fR(1) suite