You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
142 lines
4.9 KiB
142 lines
4.9 KiB
gitcli(7) |
|
========= |
|
|
|
NAME |
|
---- |
|
gitcli - git command line interface and conventions |
|
|
|
SYNOPSIS |
|
-------- |
|
gitcli |
|
|
|
|
|
DESCRIPTION |
|
----------- |
|
|
|
This manual describes the convention used throughout git CLI. |
|
|
|
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: |
|
|
|
* 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. |
|
|
|
* 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. |
|
|
|
* 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. |
|
|
|
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. |
|
|
|
Here are the rules regarding the "flags" 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 OPTION PARSER |
|
---------------------- |
|
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[1] suite
|
|
|