]>
Commit | Line | Data |
---|---|---|
a5af0e2c | 1 | gitcli(7) |
2f7ee089 PH |
2 | ========= |
3 | ||
4 | NAME | |
5 | ---- | |
06ab60c0 | 6 | gitcli - Git command-line interface and conventions |
2f7ee089 PH |
7 | |
8 | SYNOPSIS | |
9 | -------- | |
10 | gitcli | |
11 | ||
12 | ||
13 | DESCRIPTION | |
14 | ----------- | |
15 | ||
2de9b711 | 16 | This manual describes the convention used throughout Git CLI. |
d0658ec6 JH |
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 | ||
c11f9501 TL |
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 gave 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 ambiguity by enforcing the "options then args" rule). | |
30 | ||
d0658ec6 JH |
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, | |
6cf378f0 JK |
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 | |
d0658ec6 | 39 | tree. Please show changes between the version I staged in the index |
5fe8f49b | 40 | and what I have in the work tree for that file", not "show difference |
d0658ec6 | 41 | between the HEAD commit and the work tree as a whole". You can say |
6cf378f0 | 42 | `git diff HEAD --` to ask for the latter. |
d0658ec6 | 43 | |
2de9b711 | 44 | * Without disambiguating `--`, Git makes a reasonable guess, but errors |
d0658ec6 JH |
45 | out and asking 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 | |
6cf378f0 | 47 | you have to say either `git diff HEAD --` or `git diff -- HEAD` to |
d0658ec6 | 48 | disambiguate. |
67feca3b JK |
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 `--`). | |
008566e0 | 55 | + |
d0658ec6 JH |
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 | |
6cf378f0 | 58 | disambiguating `--` at appropriate places. |
d0658ec6 | 59 | |
8300016e JH |
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 | -------------------------------- | |
80f537f7 NTND |
65 | $ git restore *.c |
66 | $ git restore \*.c | |
8300016e JH |
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 | ||
08f8d5d0 PO |
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. | |
8300016e | 80 | |
d0658ec6 | 81 | Here are the rules regarding the "flags" that you should follow when you are |
2de9b711 | 82 | scripting Git: |
2f7ee089 | 83 | |
c11f9501 | 84 | * It's preferred to use the non-dashed form of Git commands, which means that |
dcb11263 | 85 | you should prefer `git foo` to `git-foo`. |
2f7ee089 | 86 | |
c11f9501 | 87 | * Splitting short options to separate words (prefer `git foo -a -b` |
dcb11263 | 88 | to `git foo -ab`, the latter may not even work). |
2f7ee089 | 89 | |
c11f9501 | 90 | * When a command-line option takes an argument, use the 'stuck' form. In |
dcb11263 CJ |
91 | other words, write `git foo -oArg` instead of `git foo -o Arg` for short |
92 | options, and `git foo --long-opt=Arg` instead of `git foo --long-opt Arg` | |
2f7ee089 | 93 | for long options. An option that takes optional option-argument must be |
b0d12fc9 | 94 | written in the 'stuck' form. |
2f7ee089 | 95 | |
c11f9501 | 96 | * When you give a revision parameter to a command, make sure the parameter is |
2f7ee089 | 97 | not ambiguous with a name of a file in the work tree. E.g. do not write |
dcb11263 | 98 | `git log -1 HEAD` but write `git log -1 HEAD --`; the former will not work |
2f7ee089 PH |
99 | if you happen to have a file called `HEAD` in the work tree. |
100 | ||
c11f9501 | 101 | * Many commands allow a long option `--option` to be abbreviated |
9c81990b | 102 | only to their unique prefix (e.g. if there is no other option |
0b7e4e0d JSJ |
103 | whose name begins with `opt`, you may be able to spell `--opt` to |
104 | invoke the `--option` flag), but you should fully spell them out | |
9c81990b | 105 | when writing your scripts; later versions of Git may introduce a |
0b7e4e0d | 106 | new option whose name shares the same prefix, e.g. `--optimize`, |
9c81990b JH |
107 | to make a short prefix that used to be unique no longer unique. |
108 | ||
2f7ee089 | 109 | |
d0658ec6 JH |
110 | ENHANCED OPTION PARSER |
111 | ---------------------- | |
2de9b711 | 112 | From the Git 1.5.4 series and further, many Git commands (not all of them at the |
2f7ee089 PH |
113 | time of the writing though) come with an enhanced option parser. |
114 | ||
30462a74 | 115 | Here is a list of the facilities provided by this option parser. |
2f7ee089 PH |
116 | |
117 | ||
118 | Magic Options | |
119 | ~~~~~~~~~~~~~ | |
120 | Commands which have the enhanced option parser activated all understand a | |
06ab60c0 | 121 | couple of magic command-line options: |
2f7ee089 PH |
122 | |
123 | -h:: | |
124 | gives a pretty printed usage of the command. | |
125 | + | |
126 | --------------------------------------------- | |
127 | $ git describe -h | |
de613050 RD |
128 | usage: git describe [<options>] <commit-ish>* |
129 | or: git describe [<options>] --dirty | |
2f7ee089 PH |
130 | |
131 | --contains find the tag that comes after the commit | |
132 | --debug debug search strategy on stderr | |
48dfe969 GP |
133 | --all use any ref |
134 | --tags use any tag, even unannotated | |
135 | --long always use long format | |
136 | --abbrev[=<n>] use <n> digits to display SHA-1s | |
2f7ee089 | 137 | --------------------------------------------- |
1ff466c0 JH |
138 | + |
139 | Note that some subcommand (e.g. `git grep`) may behave differently | |
140 | when there are things on the command line other than `-h`, but `git | |
141 | subcmd -h` without anything else on the command line is meant to | |
142 | consistently give the usage. | |
2f7ee089 PH |
143 | |
144 | --help-all:: | |
2de9b711 | 145 | Some Git commands take options that are only used for plumbing or that |
2f7ee089 PH |
146 | are deprecated, and such options are hidden from the default usage. This |
147 | option gives the full list of options. | |
148 | ||
149 | ||
150 | Negating options | |
151 | ~~~~~~~~~~~~~~~~ | |
dcb11263 CJ |
152 | Options with long option names can be negated by prefixing `--no-`. For |
153 | example, `git branch` has the option `--track` which is 'on' by default. You | |
154 | can use `--no-track` to override that behaviour. The same goes for `--color` | |
155 | and `--no-color`. | |
2f7ee089 PH |
156 | |
157 | ||
158 | Aggregating short options | |
159 | ~~~~~~~~~~~~~~~~~~~~~~~~~ | |
160 | Commands that support the enhanced option parser allow you to aggregate short | |
dcb11263 CJ |
161 | options. This means that you can for example use `git rm -rf` or |
162 | `git clean -fdx`. | |
2f7ee089 PH |
163 | |
164 | ||
30462a74 JH |
165 | Abbreviating long options |
166 | ~~~~~~~~~~~~~~~~~~~~~~~~~ | |
167 | Commands that support the enhanced option parser accepts unique | |
168 | prefix of a long option as if it is fully spelled out, but use this | |
169 | with a caution. For example, `git commit --amen` behaves as if you | |
170 | typed `git commit --amend`, but that is true only until a later version | |
171 | of Git introduces another option that shares the same prefix, | |
0b7e4e0d | 172 | e.g. `git commit --amenity` option. |
30462a74 JH |
173 | |
174 | ||
2f7ee089 PH |
175 | Separating argument from the option |
176 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
177 | You can write the mandatory option parameter to an option as a separate | |
178 | word on the command line. That means that all the following uses work: | |
179 | ||
180 | ---------------------------- | |
181 | $ git foo --long-opt=Arg | |
182 | $ git foo --long-opt Arg | |
183 | $ git foo -oArg | |
184 | $ git foo -o Arg | |
185 | ---------------------------- | |
186 | ||
f1cdcc70 | 187 | However, this is *NOT* allowed for switches with an optional value, where the |
b0d12fc9 | 188 | 'stuck' form must be used: |
2f7ee089 PH |
189 | ---------------------------- |
190 | $ git describe --abbrev HEAD # correct | |
191 | $ git describe --abbrev=10 HEAD # correct | |
192 | $ git describe --abbrev 10 HEAD # NOT WHAT YOU MEANT | |
193 | ---------------------------- | |
194 | ||
195 | ||
aa0c1f20 NS |
196 | NOTES ON FREQUENTLY CONFUSED OPTIONS |
197 | ------------------------------------ | |
198 | ||
199 | Many commands that can work on files in the working tree | |
200 | and/or in the index can take `--cached` and/or `--index` | |
201 | options. Sometimes people incorrectly think that, because | |
202 | the index was originally called cache, these two are | |
203 | synonyms. They are *not* -- these two options mean very | |
204 | different things. | |
205 | ||
206 | * The `--cached` option is used to ask a command that | |
207 | usually works on files in the working tree to *only* work | |
208 | with the index. For example, `git grep`, when used | |
209 | without a commit to specify from which commit to look for | |
210 | strings in, usually works on files in the working tree, | |
211 | but with the `--cached` option, it looks for strings in | |
212 | the index. | |
213 | ||
214 | * The `--index` option is used to ask a command that | |
215 | usually works on files in the working tree to *also* | |
216 | affect the index. For example, `git stash apply` usually | |
e01db917 | 217 | merges changes recorded in a stash entry to the working tree, |
aa0c1f20 NS |
218 | but with the `--index` option, it also merges changes to |
219 | the index as well. | |
220 | ||
221 | `git apply` command can be used with `--cached` and | |
222 | `--index` (but not at the same time). Usually the command | |
223 | only affects the files in the working tree, but with | |
224 | `--index`, it patches both the files and their index | |
225 | entries, and with `--cached`, it modifies only the index | |
226 | entries. | |
227 | ||
dcee0372 DL |
228 | See also https://lore.kernel.org/git/7v64clg5u9.fsf@assigned-by-dhcp.cox.net/ and |
229 | https://lore.kernel.org/git/7vy7ej9g38.fsf@gitster.siamese.dyndns.org/ for further | |
aa0c1f20 NS |
230 | information. |
231 | ||
46e91b66 NTND |
232 | Some other commands that also work on files in the working tree and/or |
233 | in the index can take `--staged` and/or `--worktree`. | |
234 | ||
235 | * `--staged` is exactly like `--cached`, which is used to ask a | |
236 | command to only work on the index, not the working tree. | |
237 | ||
238 | * `--worktree` is the opposite, to ask a command to work on the | |
239 | working tree only, not the index. | |
240 | ||
241 | * The two options can be specified together to ask a command to work | |
242 | on both the index and the working tree. | |
243 | ||
2f7ee089 PH |
244 | GIT |
245 | --- | |
9e1f0a85 | 246 | Part of the linkgit:git[1] suite |