path: root/man7/gitcli.7

'\" t
.\"     Title: gitcli
.\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 2024-04-29
.\"    Manual: Git Manual
.\"    Source: Git 2.45.0
.\"  Language: English
.\"
.TH "GITCLI" "7" "2024\-04\-29" "Git 2\&.45\&.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 diff v1\&.0 v2\&.0 arch/x86 include/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 diff \-\- HEAD\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 diff HEAD \-\-\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 diff HEAD\fR
is ambiguous, and you have to say either
\fBgit diff HEAD \-\-\fR
or
\fBgit diff \-\- HEAD\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
\fB*\&.c\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 add hello\&.c; rm hello\&.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 foo \-a \-b\fR
to
\fBgit foo \-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 foo \-oArg\fR
instead of
\fBgit foo \-o Arg\fR
for short options, and
\fBgit foo \-\-long\-opt=Arg\fR
instead of
\fBgit foo \-\-long\-opt Arg\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
.\}
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 log \-1 HEAD\fR
but write
\fBgit log \-1 HEAD \-\-\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 grep\fR) may behave differently when there are things on the command line other than
\fB\-h\fR, but
\fBgit subcmd \-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 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\&.
.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 rm \-rf\fR or \fBgit clean \-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 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\&.
.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
.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
.\}
.sp
.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 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
\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 stash apply\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 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\&.
.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