| 1 | gitcli(7) |
| 2 | ========= |
| 3 | |
| 4 | NAME |
| 5 | ---- |
| 6 | gitcli - Git command-line interface and conventions |
| 7 | |
| 8 | SYNOPSIS |
| 9 | -------- |
| 10 | gitcli |
| 11 | |
| 12 | |
| 13 | DESCRIPTION |
| 14 | ----------- |
| 15 | |
| 16 | This manual describes the convention used throughout Git CLI. |
| 17 | |
| 18 | Many commands take revisions (most often "commits", but sometimes |
| 19 | "tree-ish", depending on the context and command) and paths as their |
| 20 | arguments. Here are the rules: |
| 21 | |
| 22 | * Options come first and then args. |
| 23 | A subcommand may take dashed options (which may take their own |
| 24 | arguments, e.g. "--max-parents 2") and arguments. You SHOULD |
| 25 | give dashed options first and then arguments. Some commands may |
| 26 | accept dashed options after you have already given non-option |
| 27 | arguments (which may make the command ambiguous), but you should |
| 28 | not rely on it (because eventually we may find a way to fix |
| 29 | these ambiguities by enforcing the "options then args" rule). |
| 30 | |
| 31 | * Revisions come first and then paths. |
| 32 | E.g. in `git diff v1.0 v2.0 arch/x86 include/asm-x86`, |
| 33 | `v1.0` and `v2.0` are revisions and `arch/x86` and `include/asm-x86` |
| 34 | are paths. |
| 35 | |
| 36 | * When an argument can be misunderstood as either a revision or a path, |
| 37 | they can be disambiguated by placing `--` between them. |
| 38 | E.g. `git diff -- HEAD` is, "I have a file called HEAD in my work |
| 39 | tree. Please show changes between the version I staged in the index |
| 40 | and what I have in the work tree for that file", not "show the difference |
| 41 | between the HEAD commit and the work tree as a whole". You can say |
| 42 | `git diff HEAD --` to ask for the latter. |
| 43 | |
| 44 | * Without disambiguating `--`, Git makes a reasonable guess, but errors |
| 45 | out and asks you to disambiguate when ambiguous. E.g. if you have a |
| 46 | file called HEAD in your work tree, `git diff HEAD` is ambiguous, and |
| 47 | you have to say either `git diff HEAD --` or `git diff -- HEAD` to |
| 48 | disambiguate. |
| 49 | |
| 50 | * Because `--` disambiguates revisions and paths in some commands, it |
| 51 | cannot be used for those commands to separate options and revisions. |
| 52 | You can use `--end-of-options` for this (it also works for commands |
| 53 | that do not distinguish between revisions in paths, in which case it |
| 54 | is simply an alias for `--`). |
| 55 | + |
| 56 | When writing a script that is expected to handle random user-input, it is |
| 57 | a good practice to make it explicit which arguments are which by placing |
| 58 | disambiguating `--` at appropriate places. |
| 59 | |
| 60 | * Many commands allow wildcards in paths, but you need to protect |
| 61 | them from getting globbed by the shell. These two mean different |
| 62 | things: |
| 63 | + |
| 64 | -------------------------------- |
| 65 | $ git restore *.c |
| 66 | $ git restore \*.c |
| 67 | -------------------------------- |
| 68 | + |
| 69 | The former lets your shell expand the fileglob, and you are asking |
| 70 | the dot-C files in your working tree to be overwritten with the version |
| 71 | in the index. The latter passes the `*.c` to Git, and you are asking |
| 72 | the paths in the index that match the pattern to be checked out to your |
| 73 | working tree. After running `git add hello.c; rm hello.c`, you will _not_ |
| 74 | see `hello.c` in your working tree with the former, but with the latter |
| 75 | you will. |
| 76 | |
| 77 | * Just as the filesystem '.' (period) refers to the current directory, |
| 78 | using a '.' as a repository name in Git (a dot-repository) is a relative |
| 79 | path and means your current repository. |
| 80 | |
| 81 | Here are the rules regarding the "flags" that you should follow when you are |
| 82 | scripting Git: |
| 83 | |
| 84 | * Splitting short options to separate words (prefer `git foo -a -b` |
| 85 | to `git foo -ab`, the latter may not even work). |
| 86 | |
| 87 | * When a command-line option takes an argument, use the 'stuck' form. In |
| 88 | other words, write `git foo -oArg` instead of `git foo -o Arg` for short |
| 89 | options, and `git foo --long-opt=Arg` instead of `git foo --long-opt Arg` |
| 90 | for long options. An option that takes optional option-argument must be |
| 91 | written in the 'stuck' form. |
| 92 | |
| 93 | * Despite the above suggestion, when Arg is a path relative to the |
| 94 | home directory of a user, e.g. `~/directory/file` or `~u/d/f`, you |
| 95 | may want to use the separate form, e.g. `git foo --file ~/mine`, |
| 96 | not `git foo --file=~/mine`. The shell will expand `~/` in the |
| 97 | former to your home directory, but most shells keep the tilde in |
| 98 | the latter. Some of our commands know how to tilde-expand the |
| 99 | option value even when given in the stuck form, but not all of |
| 100 | them do. |
| 101 | |
| 102 | * When you give a revision parameter to a command, make sure the parameter is |
| 103 | not ambiguous with a name of a file in the work tree. E.g. do not write |
| 104 | `git log -1 HEAD` but write `git log -1 HEAD --`; the former will not work |
| 105 | if you happen to have a file called `HEAD` in the work tree. |
| 106 | |
| 107 | * Many commands allow a long option `--option` to be abbreviated |
| 108 | only to their unique prefix (e.g. if there is no other option |
| 109 | whose name begins with `opt`, you may be able to spell `--opt` to |
| 110 | invoke the `--option` flag), but you should fully spell them out |
| 111 | when writing your scripts; later versions of Git may introduce a |
| 112 | new option whose name shares the same prefix, e.g. `--optimize`, |
| 113 | to make a short prefix that used to be unique no longer unique. |
| 114 | |
| 115 | |
| 116 | ENHANCED OPTION PARSER |
| 117 | ---------------------- |
| 118 | From the Git 1.5.4 series and further, many Git commands (not all of them at the |
| 119 | time of the writing though) come with an enhanced option parser. |
| 120 | |
| 121 | Here is a list of the facilities provided by this option parser. |
| 122 | |
| 123 | |
| 124 | Magic Options |
| 125 | ~~~~~~~~~~~~~ |
| 126 | Commands which have the enhanced option parser activated all understand a |
| 127 | couple of magic command-line options: |
| 128 | |
| 129 | -h:: |
| 130 | gives a pretty printed usage of the command. |
| 131 | + |
| 132 | --------------------------------------------- |
| 133 | $ git describe -h |
| 134 | usage: git describe [<options>] <commit-ish>* |
| 135 | or: git describe [<options>] --dirty |
| 136 | |
| 137 | --contains find the tag that comes after the commit |
| 138 | --debug debug search strategy on stderr |
| 139 | --all use any ref |
| 140 | --tags use any tag, even unannotated |
| 141 | --long always use long format |
| 142 | --abbrev[=<n>] use <n> digits to display SHA-1s |
| 143 | --------------------------------------------- |
| 144 | + |
| 145 | Note that some subcommand (e.g. `git grep`) may behave differently |
| 146 | when there are things on the command line other than `-h`, but `git |
| 147 | subcmd -h` without anything else on the command line is meant to |
| 148 | consistently give the usage. |
| 149 | |
| 150 | --help-all:: |
| 151 | Some Git commands take options that are only used for plumbing or that |
| 152 | are deprecated, and such options are hidden from the default usage. This |
| 153 | option gives the full list of options. |
| 154 | |
| 155 | |
| 156 | Negating options |
| 157 | ~~~~~~~~~~~~~~~~ |
| 158 | Options with long option names can be negated by prefixing `--no-`. For |
| 159 | example, `git branch` has the option `--track` which is 'on' by default. You |
| 160 | can use `--no-track` to override that behaviour. The same goes for `--color` |
| 161 | and `--no-color`. |
| 162 | |
| 163 | |
| 164 | Options trump configuration and environment |
| 165 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 166 | |
| 167 | When there is a configuration variable or an environment variable |
| 168 | that tweak the behaviour of an aspect of a Git command, and also a |
| 169 | command line option that tweaks the same, the command line option |
| 170 | overrides what the configuration and/or environment variable say. |
| 171 | |
| 172 | For example, the `user.name` configuration variable is used to |
| 173 | specify the human-readable name used by the `git commit` command to |
| 174 | record the author and the committer name in a newly created commit. |
| 175 | The `GIT_AUTHOR_NAME` environment variable, if set, takes precedence |
| 176 | when deciding what author name to record. The `--author=<author>` |
| 177 | command line option of the `git commit` command, when given, takes |
| 178 | precedence over these two sources of information. |
| 179 | |
| 180 | |
| 181 | Aggregating short options |
| 182 | ~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 183 | Commands that support the enhanced option parser allow you to aggregate short |
| 184 | options. This means that you can for example use `git rm -rf` or |
| 185 | `git clean -fdx`. |
| 186 | |
| 187 | |
| 188 | Abbreviating long options |
| 189 | ~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 190 | Commands that support the enhanced option parser accepts unique |
| 191 | prefix of a long option as if it is fully spelled out, but use this |
| 192 | with a caution. For example, `git commit --amen` behaves as if you |
| 193 | typed `git commit --amend`, but that is true only until a later version |
| 194 | of Git introduces another option that shares the same prefix, |
| 195 | e.g. `git commit --amenity` option. |
| 196 | |
| 197 | |
| 198 | Separating argument from the option |
| 199 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 200 | You can write the mandatory option parameter to an option as a separate |
| 201 | word on the command line. That means that all the following uses work: |
| 202 | |
| 203 | ---------------------------- |
| 204 | $ git foo --long-opt=Arg |
| 205 | $ git foo --long-opt Arg |
| 206 | $ git foo -oArg |
| 207 | $ git foo -o Arg |
| 208 | ---------------------------- |
| 209 | |
| 210 | However, this is *NOT* allowed for switches with an optional value, where the |
| 211 | 'stuck' form must be used: |
| 212 | |
| 213 | ---------------------------- |
| 214 | $ git describe --abbrev HEAD # correct |
| 215 | $ git describe --abbrev=10 HEAD # correct |
| 216 | $ git describe --abbrev 10 HEAD # NOT WHAT YOU MEANT |
| 217 | ---------------------------- |
| 218 | |
| 219 | |
| 220 | Magic filename options |
| 221 | ~~~~~~~~~~~~~~~~~~~~~~ |
| 222 | Options that take a filename allow a prefix `:(optional)`. For example: |
| 223 | |
| 224 | ---------------------------- |
| 225 | git commit -F :(optional)COMMIT_EDITMSG |
| 226 | # if COMMIT_EDITMSG does not exist, the above is equivalent to |
| 227 | git commit |
| 228 | ---------------------------- |
| 229 | |
| 230 | Like with configuration values, if the named file is missing Git behaves as if |
| 231 | the option was not given at all. See "Values" in linkgit:git-config[1]. |
| 232 | |
| 233 | NOTES ON FREQUENTLY CONFUSED OPTIONS |
| 234 | ------------------------------------ |
| 235 | |
| 236 | Many commands that can work on files in the working tree |
| 237 | and/or in the index can take `--cached` and/or `--index` |
| 238 | options. Sometimes people incorrectly think that, because |
| 239 | the index was originally called cache, these two are |
| 240 | synonyms. They are *not* -- these two options mean very |
| 241 | different things. |
| 242 | |
| 243 | * The `--cached` option is used to ask a command that |
| 244 | usually works on files in the working tree to *only* work |
| 245 | with the index. For example, `git grep`, when used |
| 246 | without a commit to specify from which commit to look for |
| 247 | strings in, usually works on files in the working tree, |
| 248 | but with the `--cached` option, it looks for strings in |
| 249 | the index. |
| 250 | |
| 251 | * The `--index` option is used to ask a command that |
| 252 | usually works on files in the working tree to *also* |
| 253 | affect the index. For example, `git stash apply` usually |
| 254 | merges changes recorded in a stash entry to the working tree, |
| 255 | but with the `--index` option, it also merges changes to |
| 256 | the index as well. |
| 257 | |
| 258 | `git apply` command can be used with `--cached` and |
| 259 | `--index` (but not at the same time). Usually the command |
| 260 | only affects the files in the working tree, but with |
| 261 | `--index`, it patches both the files and their index |
| 262 | entries, and with `--cached`, it modifies only the index |
| 263 | entries. |
| 264 | |
| 265 | See also https://lore.kernel.org/git/7v64clg5u9.fsf@assigned-by-dhcp.cox.net/ and |
| 266 | https://lore.kernel.org/git/7vy7ej9g38.fsf@gitster.siamese.dyndns.org/ for further |
| 267 | information. |
| 268 | |
| 269 | Some other commands that also work on files in the working tree and/or |
| 270 | in the index can take `--staged` and/or `--worktree`. |
| 271 | |
| 272 | * `--staged` is exactly like `--cached`, which is used to ask a |
| 273 | command to only work on the index, not the working tree. |
| 274 | |
| 275 | * `--worktree` is the opposite, to ask a command to work on the |
| 276 | working tree only, not the index. |
| 277 | |
| 278 | * The two options can be specified together to ask a command to work |
| 279 | on both the index and the working tree. |
| 280 | |
| 281 | GIT |
| 282 | --- |
| 283 | Part of the linkgit:git[1] suite |