114 lines
3.5 KiB
Plaintext
114 lines
3.5 KiB
Plaintext
gitcli(5)
|
|
=========
|
|
|
|
NAME
|
|
----
|
|
gitcli - git command line interface and conventions
|
|
|
|
SYNOPSIS
|
|
--------
|
|
gitcli
|
|
|
|
|
|
DESCRIPTION
|
|
-----------
|
|
|
|
This manual describes best practice in how to use git CLI. Here are
|
|
the rules that you should follow when you are scripting git:
|
|
|
|
* it's preferred to use the non dashed form of git commands, which means that
|
|
you should prefer `"git foo"` to `"git-foo"`.
|
|
|
|
* splitting short options to separate words (prefer `"git foo -a -b"`
|
|
to `"git foo -ab"`, the latter may not even work).
|
|
|
|
* when a command line option takes an argument, use the 'sticked' 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 'sticked' form.
|
|
|
|
* 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.
|
|
|
|
|
|
ENHANCED CLI
|
|
------------
|
|
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.
|
|
|
|
Here is an exhaustive list of the facilities provided by this option parser.
|
|
|
|
|
|
Magic Options
|
|
~~~~~~~~~~~~~
|
|
Commands which have the enhanced option parser activated all understand a
|
|
couple of magic command line options:
|
|
|
|
-h::
|
|
gives a pretty printed usage of the command.
|
|
+
|
|
---------------------------------------------
|
|
$ git describe -h
|
|
usage: git-describe [options] <committish>*
|
|
|
|
--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 [<n>] use <n> digits to display SHA-1s
|
|
--candidates <n> consider <n> most recent tags (default: 10)
|
|
---------------------------------------------
|
|
|
|
--help-all::
|
|
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.
|
|
|
|
|
|
Negating options
|
|
~~~~~~~~~~~~~~~~
|
|
Options with long option names can be negated by prefixing `"--no-"`. For
|
|
example, `"git branch"` has the option `"--track"` which is 'on' by default. You
|
|
can use `"--no-track"` to override that behaviour. The same goes for `"--color"`
|
|
and `"--no-color"`.
|
|
|
|
|
|
Aggregating short options
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
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"`.
|
|
|
|
|
|
Separating argument from the option
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
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:
|
|
|
|
----------------------------
|
|
$ git foo --long-opt=Arg
|
|
$ git foo --long-opt Arg
|
|
$ git foo -oArg
|
|
$ git foo -o Arg
|
|
----------------------------
|
|
|
|
However, this is *NOT* allowed for switches with an optional value, where the
|
|
'sticked' form must be used:
|
|
----------------------------
|
|
$ git describe --abbrev HEAD # correct
|
|
$ git describe --abbrev=10 HEAD # correct
|
|
$ git describe --abbrev 10 HEAD # NOT WHAT YOU MEANT
|
|
----------------------------
|
|
|
|
|
|
Documentation
|
|
-------------
|
|
Documentation by Pierre Habouzit.
|
|
|
|
GIT
|
|
---
|
|
Part of the linkgit:git[7] suite
|