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 136NOTES ON FREQUENTLY CONFUSED OPTIONS 137------------------------------------ 138 139Many commands that can work on files in the working tree 140and/or in the index can take `--cached` and/or `--index` 141options. Sometimes people incorrectly think that, because 142the index was originally called cache, these two are 143synonyms. They are *not* -- these two options mean very 144different things. 145 146 * The `--cached` option is used to ask a command that 147 usually works on files in the working tree to *only* work 148 with the index. For example, `git grep`, when used 149 without a commit to specify from which commit to look for 150 strings in, usually works on files in the working tree, 151 but with the `--cached` option, it looks for strings in 152 the index. 153 154 * The `--index` option is used to ask a command that 155 usually works on files in the working tree to *also* 156 affect the index. For example, `git stash apply` usually 157 merges changes recorded in a stash to the working tree, 158 but with the `--index` option, it also merges changes to 159 the index as well. 160 161`git apply` command can be used with `--cached` and 162`--index` (but not at the same time). Usually the command 163only affects the files in the working tree, but with 164`--index`, it patches both the files and their index 165entries, and with `--cached`, it modifies only the index 166entries. 167 168See also http://marc.info/?l=git&m=116563135620359 and 169http://marc.info/?l=git&m=119150393620273 for further 170information. 171 172GIT 173--- 174Part of the linkgit:git[1] suite