]>
Commit | Line | Data |
---|---|---|
a5af0e2c | 1 | gitcli(7) |
2f7ee089 PH |
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 | ||
d0658ec6 JH |
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 | * 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 | ||
41 | When writing a script that is expected to handle random user-input, it is | |
42 | a good practice to make it explicit which arguments are which by placing | |
43 | disambiguating `\--` at appropriate places. | |
44 | ||
45 | Here are the rules regarding the "flags" that you should follow when you are | |
46 | scripting git: | |
2f7ee089 PH |
47 | |
48 | * it's preferred to use the non dashed form of git commands, which means that | |
dcb11263 | 49 | you should prefer `git foo` to `git-foo`. |
2f7ee089 | 50 | |
dcb11263 CJ |
51 | * splitting short options to separate words (prefer `git foo -a -b` |
52 | to `git foo -ab`, the latter may not even work). | |
2f7ee089 PH |
53 | |
54 | * when a command line option takes an argument, use the 'sticked' form. In | |
dcb11263 CJ |
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` | |
2f7ee089 PH |
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 | |
dcb11263 | 62 | `git log -1 HEAD` but write `git log -1 HEAD --`; the former will not work |
2f7ee089 PH |
63 | if you happen to have a file called `HEAD` in the work tree. |
64 | ||
65 | ||
d0658ec6 JH |
66 | ENHANCED OPTION PARSER |
67 | ---------------------- | |
2f7ee089 PH |
68 | From the git 1.5.4 series and further, many git commands (not all of them at the |
69 | time of the writing though) come with an enhanced option parser. | |
70 | ||
71 | Here is an exhaustive list of the facilities provided by this option parser. | |
72 | ||
73 | ||
74 | Magic Options | |
75 | ~~~~~~~~~~~~~ | |
76 | Commands which have the enhanced option parser activated all understand a | |
77 | couple of magic command line options: | |
78 | ||
79 | -h:: | |
80 | gives a pretty printed usage of the command. | |
81 | + | |
82 | --------------------------------------------- | |
83 | $ git describe -h | |
3ddcb198 | 84 | usage: git describe [options] <committish>* |
2f7ee089 PH |
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 | ||
100 | Negating options | |
101 | ~~~~~~~~~~~~~~~~ | |
dcb11263 CJ |
102 | Options with long option names can be negated by prefixing `--no-`. For |
103 | example, `git branch` has the option `--track` which is 'on' by default. You | |
104 | can use `--no-track` to override that behaviour. The same goes for `--color` | |
105 | and `--no-color`. | |
2f7ee089 PH |
106 | |
107 | ||
108 | Aggregating short options | |
109 | ~~~~~~~~~~~~~~~~~~~~~~~~~ | |
110 | Commands that support the enhanced option parser allow you to aggregate short | |
dcb11263 CJ |
111 | options. This means that you can for example use `git rm -rf` or |
112 | `git clean -fdx`. | |
2f7ee089 PH |
113 | |
114 | ||
115 | Separating argument from the option | |
116 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
117 | You can write the mandatory option parameter to an option as a separate | |
118 | word 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 | ||
f1cdcc70 | 127 | However, this is *NOT* allowed for switches with an optional value, where the |
2f7ee089 PH |
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 | ||
aa0c1f20 NS |
136 | NOTES ON FREQUENTLY CONFUSED OPTIONS |
137 | ------------------------------------ | |
138 | ||
139 | Many commands that can work on files in the working tree | |
140 | and/or in the index can take `--cached` and/or `--index` | |
141 | options. Sometimes people incorrectly think that, because | |
142 | the index was originally called cache, these two are | |
143 | synonyms. They are *not* -- these two options mean very | |
144 | different 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 | |
163 | only affects the files in the working tree, but with | |
164 | `--index`, it patches both the files and their index | |
165 | entries, and with `--cached`, it modifies only the index | |
166 | entries. | |
167 | ||
168 | See also http://marc.info/?l=git&m=116563135620359 and | |
169 | http://marc.info/?l=git&m=119150393620273 for further | |
170 | information. | |
171 | ||
2f7ee089 PH |
172 | Documentation |
173 | ------------- | |
aa0c1f20 | 174 | Documentation by Pierre Habouzit and the git-list <git@vger.kernel.org>. |
2f7ee089 PH |
175 | |
176 | GIT | |
177 | --- | |
9e1f0a85 | 178 | Part of the linkgit:git[1] suite |