1gitcli(7) 2========= 3 4NAME 5---- 6gitcli - git command line interface and conventions 7 8SYNOPSIS 9-------- 10gitcli 11 12 13DESCRIPTION 14----------- 15 16This manual describes the convention used throughout git CLI. 17 18Many commands take revisions (most often "commits", but sometimes 19"tree-ish", depending on the context and command) and paths as their 20arguments. Here are the rules: 21 22 * Revisions come first and then paths. 23 E.g. in `git diff v1.0 v2.0 arch/x86 include/asm-x86`, 24 `v1.0` and `v2.0` are revisions and `arch/x86` and `include/asm-x86` 25 are paths. 26 27 * When an argument can be misunderstood as either a revision or a path, 28 they can be disambiguated by placing `\--` between them. 29 E.g. `git diff \-- HEAD` is, "I have a file called HEAD in my work 30 tree. Please show changes between the version I staged in the index 31 and what I have in the work tree for that file". not "show difference 32 between the HEAD commit and the work tree as a whole". You can say 33 `git diff HEAD \--` to ask for the latter. 34 35 * Without disambiguating `\--`, git makes a reasonable guess, but errors 36 out and asking you to disambiguate when ambiguous. E.g. if you have a 37 file called HEAD in your work tree, `git diff HEAD` is ambiguous, and 38 you have to say either `git diff HEAD \--` or `git diff \-- HEAD` to 39 disambiguate. 40 41When writing a script that is expected to handle random user-input, it is 42a good practice to make it explicit which arguments are which by placing 43disambiguating `\--` at appropriate places. 44 45Here are the rules regarding the "flags" that you should follow when you are 46scripting git: 47 48 * it's preferred to use the non dashed form of git commands, which means that 49 you should prefer `"git foo"` to `"git-foo"`. 50 51 * splitting short options to separate words (prefer `"git foo -a -b"` 52 to `"git foo -ab"`, the latter may not even work). 53 54 * when a command line option takes an argument, use the 'sticked' form. In 55 other words, write `"git foo -oArg"` instead of `"git foo -o Arg"` for short 56 options, and `"git foo --long-opt=Arg"` instead of `"git foo --long-opt Arg"` 57 for long options. An option that takes optional option-argument must be 58 written in the 'sticked' form. 59 60 * when you give a revision parameter to a command, make sure the parameter is 61 not ambiguous with a name of a file in the work tree. E.g. do not write 62 `"git log -1 HEAD"` but write `"git log -1 HEAD --"`; the former will not work 63 if you happen to have a file called `HEAD` in the work tree. 64 65 66ENHANCED OPTION PARSER 67---------------------- 68From the git 1.5.4 series and further, many git commands (not all of them at the 69time of the writing though) come with an enhanced option parser. 70 71Here is an exhaustive list of the facilities provided by this option parser. 72 73 74Magic Options 75~~~~~~~~~~~~~ 76Commands which have the enhanced option parser activated all understand a 77couple of magic command line options: 78 79-h:: 80 gives a pretty printed usage of the command. 81+ 82--------------------------------------------- 83$ git describe -h 84usage: git-describe [options] <committish>* 85 86 --contains find the tag that comes after the commit 87 --debug debug search strategy on stderr 88 --all use any ref in .git/refs 89 --tags use any tag in .git/refs/tags 90 --abbrev [<n>] use <n> digits to display SHA-1s 91 --candidates <n> consider <n> most recent tags (default: 10) 92--------------------------------------------- 93 94--help-all:: 95 Some git commands take options that are only used for plumbing or that 96 are deprecated, and such options are hidden from the default usage. This 97 option gives the full list of options. 98 99 100Negating options 101~~~~~~~~~~~~~~~~ 102Options with long option names can be negated by prefixing `"--no-"`. For 103example, `"git branch"` has the option `"--track"` which is 'on' by default. You 104can use `"--no-track"` to override that behaviour. The same goes for `"--color"` 105and `"--no-color"`. 106 107 108Aggregating short options 109~~~~~~~~~~~~~~~~~~~~~~~~~ 110Commands that support the enhanced option parser allow you to aggregate short 111options. This means that you can for example use `"git rm -rf"` or 112`"git clean -fdx"`. 113 114 115Separating argument from the option 116~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 117You can write the mandatory option parameter to an option as a separate 118word on the command line. That means that all the following uses work: 119 120---------------------------- 121$ git foo --long-opt=Arg 122$ git foo --long-opt Arg 123$ git foo -oArg 124$ git foo -o Arg 125---------------------------- 126 127However, this is *NOT* allowed for switches with an optional value, where the 128'sticked' form must be used: 129---------------------------- 130$ git describe --abbrev HEAD # correct 131$ git describe --abbrev=10 HEAD # correct 132$ git describe --abbrev 10 HEAD # NOT WHAT YOU MEANT 133---------------------------- 134 135 136Documentation 137------------- 138Documentation by Pierre Habouzit. 139 140GIT 141--- 142Part of the linkgit:git[1] suite