'\" t
.\"     Title: gitcli
.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\"      Date: 04/04/2016
.\"    Manual: Git Manual
.\"    Source: Git 2.8.0
.\"  Language: English
.\"
.TH "GITCLI" "5" "04/04/2016" "Git 2\&.8\&.0" "Git Manual"
.\" -----------------------------------------------------------------
.\" * 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
.\}
Revisions come first and then paths\&. E\&.g\&. in
git diff v1\&.0 v2\&.0 arch/x86 include/asm\-x86,
v1\&.0
and
v2\&.0
are revisions and
arch/x86
and
include/asm\-x86
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
\-\-
between them\&. E\&.g\&.
git diff \-\- HEAD
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
git diff HEAD \-\-
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
\-\-, 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,
git diff HEAD
is ambiguous, and you have to say either
git diff HEAD \-\-
or
git diff \-\- HEAD
to disambiguate\&.
.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
\-\-
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 checkout \-\- *\&.c
$ git checkout \-\- \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
*\&.c
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
git add hello\&.c; rm hello\&.c, you will
\fInot\fR
see
hello\&.c
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
.\}
it\(cqs preferred to use the non\-dashed form of Git commands, which means that you should prefer
git foo
to
git\-foo\&.
.RE
.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
git foo \-a \-b
to
git foo \-ab, 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
git foo \-oArg
instead of
git foo \-o Arg
for short options, and
git foo \-\-long\-opt=Arg
instead of
git foo \-\-long\-opt Arg
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
git log \-1 HEAD
but write
git log \-1 HEAD \-\-; the former will not work if you happen to have a file called
HEAD
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
\-\-option
to be abbreviated only to their unique prefix (e\&.g\&. if there is no other option whose name begins with
opt, you may be able to spell
\-\-opt
to invoke the
\-\-option
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\&.
\-\-optimize, 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
.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 \-\-no\-\&. For example, git branch has the option \-\-track which is \fIon\fR by default\&. You can use \-\-no\-track to override that behaviour\&. The same goes for \-\-color and \-\-no\-color\&.
.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 git rm \-rf or git clean \-fdx\&.
.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, git commit \-\-amen behaves as if you typed git commit \-\-amend, but that is true only until a later version of Git introduces another option that shares the same prefix, e\&.g\&. git commit \-\-amenity 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 \-\-cached and/or \-\-index 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
\-\-cached
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,
git grep, 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
\-\-cached
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
\-\-index
option is used to ask a command that usually works on files in the working tree to
\fBalso\fR
affect the index\&. For example,
git stash apply
usually merges changes recorded in a stash to the working tree, but with the
\-\-index
option, it also merges changes to the index as well\&.
.RE
.sp
git apply command can be used with \-\-cached and \-\-index (but not at the same time)\&. Usually the command only affects the files in the working tree, but with \-\-index, it patches both the files and their index entries, and with \-\-cached, it modifies only the index entries\&.
.sp
See also \m[blue]\fBhttp://marc\&.info/?l=git&m=116563135620359\fR\m[] and \m[blue]\fBhttp://marc\&.info/?l=git&m=119150393620273\fR\m[] for further information\&.
.SH "GIT"
.sp
Part of the \fBgit\fR(1) suite