'\" t
.\" Title: gitcli
.\" Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.76.1
.\" Date: 03/19/2016
.\" Manual: Git Manual
.\" Source: Git 1.7.10.4
.\" Language: English
.\"
.TH "GITCLI" "7" "03/19/2016" "Git 1\&.7\&.10\&.4" "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
.\}
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\&.
.RE
.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\&.
.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
\fIsticked\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
\fIsticked\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
.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 an exhaustive 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] *
\-\-contains find the tag that comes after the commit
\-\-debug debug search strategy on stderr
\-\-all use any ref in \&.git/refs
\-\-tags use any tag in \&.git/refs/tags
\-\-abbrev [] use digits to display SHA\-1s
\-\-candidates consider most recent tags (default: 10)
.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 "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 \fIsticked\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