Sync with 1.8.0.3
[git/git.git] / Documentation / git.txt
CommitLineData
9e1f0a85 1git(1)
2cf565c5 2======
2cf565c5
DG
3
4NAME
5----
6git - the stupid content tracker
7
8
9SYNOPSIS
10--------
8b70004b 11[verse]
68e4b552
ZJS
12'git' [--version] [--help] [-c <name>=<value>]
13 [--exec-path[=<path>]] [--html-path] [--man-path] [--info-path]
d49483f0
JT
14 [-p|--paginate|--no-pager] [--no-replace-objects] [--bare]
15 [--git-dir=<path>] [--work-tree=<path>] [--namespace=<name>]
68e4b552 16 <command> [<args>]
2cf565c5
DG
17
18DESCRIPTION
19-----------
23091e95
BF
20Git is a fast, scalable, distributed revision control system with an
21unusually rich command set that provides both high-level operations
22and full access to internals.
23
6998e4db 24See linkgit:gittutorial[7] to get started, then see
7687ae98
JH
25link:everyday.html[Everyday Git] for a useful minimum set of
26commands. The link:user-manual.html[Git User's Manual] has a more
27in-depth introduction.
cb22bc44 28
7687ae98
JH
29After you mastered the basic concepts, you can come back to this
30page to learn what commands git offers. You can learn more about
31individual git commands with "git help command". linkgit:gitcli[7]
32manual page gives you an overview of the command line command syntax.
4514ad4f 33
7687ae98
JH
34Formatted and hyperlinked version of the latest git documentation
35can be viewed at `http://git-htmldocs.googlecode.com/git/git.html`.
34b604af 36
26cfcfbf
JH
37ifdef::stalenotes[]
38[NOTE]
39============
26cfcfbf 40
2ff3f61a
JH
41You are reading the documentation for the latest (possibly
42unreleased) version of git, that is available from 'master'
43branch of the `git.git` repository.
44Documentation for older releases are available here:
43a8e4fe 45
15999998 46* link:v1.8.0.3/git.html[documentation for release 1.8.0.3]
8c7a786b
JH
47
48* release notes for
15999998 49 link:RelNotes/1.8.0.3.txt[1.8.0.3],
3e53891f 50 link:RelNotes/1.8.0.2.txt[1.8.0.2],
ed9fe755
JH
51 link:RelNotes/1.8.0.1.txt[1.8.0.1],
52 link:RelNotes/1.8.0.txt[1.8.0].
8c7a786b 53
7e201053 54* link:v1.7.12.4/git.html[documentation for release 1.7.12.4]
889d3589
JH
55
56* release notes for
7e201053 57 link:RelNotes/1.7.12.4.txt[1.7.12.4],
234cd456 58 link:RelNotes/1.7.12.3.txt[1.7.12.3],
d8cf053d 59 link:RelNotes/1.7.12.2.txt[1.7.12.2],
304b7d99 60 link:RelNotes/1.7.12.1.txt[1.7.12.1],
889d3589
JH
61 link:RelNotes/1.7.12.txt[1.7.12].
62
bafc478f 63* link:v1.7.11.7/git.html[documentation for release 1.7.11.7]
0ce2e396
JH
64
65* release notes for
bafc478f 66 link:RelNotes/1.7.11.7.txt[1.7.11.7],
e09e4024 67 link:RelNotes/1.7.11.6.txt[1.7.11.6],
cd7c0be1 68 link:RelNotes/1.7.11.5.txt[1.7.11.5],
0e4c8822 69 link:RelNotes/1.7.11.4.txt[1.7.11.4],
e6dfbcf1 70 link:RelNotes/1.7.11.3.txt[1.7.11.3],
8d141a1d 71 link:RelNotes/1.7.11.2.txt[1.7.11.2],
0e64a95a 72 link:RelNotes/1.7.11.1.txt[1.7.11.1],
0ce2e396
JH
73 link:RelNotes/1.7.11.txt[1.7.11].
74
785ee496 75* link:v1.7.10.5/git.html[documentation for release 1.7.10.5]
e8dde3e5
JH
76
77* release notes for
785ee496 78 link:RelNotes/1.7.10.5.txt[1.7.10.5],
121f71f0 79 link:RelNotes/1.7.10.4.txt[1.7.10.4],
6a6d72b1 80 link:RelNotes/1.7.10.3.txt[1.7.10.3],
b6555d73 81 link:RelNotes/1.7.10.2.txt[1.7.10.2],
bf505158 82 link:RelNotes/1.7.10.1.txt[1.7.10.1],
e8dde3e5
JH
83 link:RelNotes/1.7.10.txt[1.7.10].
84
d0f1ea60 85* link:v1.7.9.7/git.html[documentation for release 1.7.9.7]
828ea97d
JH
86
87* release notes for
d0f1ea60 88 link:RelNotes/1.7.9.7.txt[1.7.9.7],
cb2ed324 89 link:RelNotes/1.7.9.6.txt[1.7.9.6],
8ced9c90 90 link:RelNotes/1.7.9.5.txt[1.7.9.5],
a4603481 91 link:RelNotes/1.7.9.4.txt[1.7.9.4],
69f4e08f 92 link:RelNotes/1.7.9.3.txt[1.7.9.3],
78f4c9f6 93 link:RelNotes/1.7.9.2.txt[1.7.9.2],
90020e3b 94 link:RelNotes/1.7.9.1.txt[1.7.9.1],
828ea97d
JH
95 link:RelNotes/1.7.9.txt[1.7.9].
96
d9f5ef7a 97* link:v1.7.8.6/git.html[documentation for release 1.7.8.6]
406da780
JH
98
99* release notes for
d9f5ef7a 100 link:RelNotes/1.7.8.6.txt[1.7.8.6],
cb2ed324 101 link:RelNotes/1.7.8.5.txt[1.7.8.5],
c572f491 102 link:RelNotes/1.7.8.4.txt[1.7.8.4],
5f4d133f
JH
103 link:RelNotes/1.7.8.3.txt[1.7.8.3],
104 link:RelNotes/1.7.8.2.txt[1.7.8.2],
105 link:RelNotes/1.7.8.1.txt[1.7.8.1],
406da780
JH
106 link:RelNotes/1.7.8.txt[1.7.8].
107
82588584 108* link:v1.7.7.7/git.html[documentation for release 1.7.7.7]
703f05ad
JH
109
110* release notes for
82588584 111 link:RelNotes/1.7.7.7.txt[1.7.7.7],
c572f491 112 link:RelNotes/1.7.7.6.txt[1.7.7.6],
66c11f02
JH
113 link:RelNotes/1.7.7.5.txt[1.7.7.5],
114 link:RelNotes/1.7.7.4.txt[1.7.7.4],
115 link:RelNotes/1.7.7.3.txt[1.7.7.3],
116 link:RelNotes/1.7.7.2.txt[1.7.7.2],
f7d958df 117 link:RelNotes/1.7.7.1.txt[1.7.7.1],
703f05ad
JH
118 link:RelNotes/1.7.7.txt[1.7.7].
119
f174a258 120* link:v1.7.6.6/git.html[documentation for release 1.7.6.6]
f696543d
JH
121
122* release notes for
f174a258 123 link:RelNotes/1.7.6.6.txt[1.7.6.6],
15b7898c 124 link:RelNotes/1.7.6.5.txt[1.7.6.5],
63205264 125 link:RelNotes/1.7.6.4.txt[1.7.6.4],
740a8fc2 126 link:RelNotes/1.7.6.3.txt[1.7.6.3],
509d5970
JH
127 link:RelNotes/1.7.6.2.txt[1.7.6.2],
128 link:RelNotes/1.7.6.1.txt[1.7.6.1],
f696543d
JH
129 link:RelNotes/1.7.6.txt[1.7.6].
130
e5af0de2 131* link:v1.7.5.4/git.html[documentation for release 1.7.5.4]
ec014eac
JH
132
133* release notes for
e5af0de2 134 link:RelNotes/1.7.5.4.txt[1.7.5.4],
3c3e0b3c 135 link:RelNotes/1.7.5.3.txt[1.7.5.3],
3d5ae435 136 link:RelNotes/1.7.5.2.txt[1.7.5.2],
2f312e88 137 link:RelNotes/1.7.5.1.txt[1.7.5.1],
ec014eac
JH
138 link:RelNotes/1.7.5.txt[1.7.5].
139
6ceb270c 140* link:v1.7.4.5/git.html[documentation for release 1.7.4.5]
7ed863a8
JH
141
142* release notes for
6ceb270c 143 link:RelNotes/1.7.4.5.txt[1.7.4.5],
6be05591 144 link:RelNotes/1.7.4.4.txt[1.7.4.4],
cb35c064
JH
145 link:RelNotes/1.7.4.3.txt[1.7.4.3],
146 link:RelNotes/1.7.4.2.txt[1.7.4.2],
9971d6d5 147 link:RelNotes/1.7.4.1.txt[1.7.4.1],
7ed863a8
JH
148 link:RelNotes/1.7.4.txt[1.7.4].
149
685e9d91 150* link:v1.7.3.5/git.html[documentation for release 1.7.3.5]
87b50542
JH
151
152* release notes for
685e9d91 153 link:RelNotes/1.7.3.5.txt[1.7.3.5],
15368e18 154 link:RelNotes/1.7.3.4.txt[1.7.3.4],
ed94cc76 155 link:RelNotes/1.7.3.3.txt[1.7.3.3],
8a904385 156 link:RelNotes/1.7.3.2.txt[1.7.3.2],
92c1e717 157 link:RelNotes/1.7.3.1.txt[1.7.3.1],
87b50542
JH
158 link:RelNotes/1.7.3.txt[1.7.3].
159
1b974346 160* link:v1.7.2.5/git.html[documentation for release 1.7.2.5]
64fdc08d
JH
161
162* release notes for
1b974346 163 link:RelNotes/1.7.2.5.txt[1.7.2.5],
ed94cc76 164 link:RelNotes/1.7.2.4.txt[1.7.2.4],
761e742d
NP
165 link:RelNotes/1.7.2.3.txt[1.7.2.3],
166 link:RelNotes/1.7.2.2.txt[1.7.2.2],
167 link:RelNotes/1.7.2.1.txt[1.7.2.1],
168 link:RelNotes/1.7.2.txt[1.7.2].
64fdc08d 169
1b974346 170* link:v1.7.1.4/git.html[documentation for release 1.7.1.4]
d599e048
JH
171
172* release notes for
1b974346 173 link:RelNotes/1.7.1.4.txt[1.7.1.4],
ed94cc76 174 link:RelNotes/1.7.1.3.txt[1.7.1.3],
761e742d
NP
175 link:RelNotes/1.7.1.2.txt[1.7.1.2],
176 link:RelNotes/1.7.1.1.txt[1.7.1.1],
177 link:RelNotes/1.7.1.txt[1.7.1].
d599e048 178
1b974346 179* link:v1.7.0.9/git.html[documentation for release 1.7.0.9]
e923eaeb
JH
180
181* release notes for
1b974346 182 link:RelNotes/1.7.0.9.txt[1.7.0.9],
ed94cc76 183 link:RelNotes/1.7.0.8.txt[1.7.0.8],
761e742d
NP
184 link:RelNotes/1.7.0.7.txt[1.7.0.7],
185 link:RelNotes/1.7.0.6.txt[1.7.0.6],
186 link:RelNotes/1.7.0.5.txt[1.7.0.5],
187 link:RelNotes/1.7.0.4.txt[1.7.0.4],
188 link:RelNotes/1.7.0.3.txt[1.7.0.3],
189 link:RelNotes/1.7.0.2.txt[1.7.0.2],
190 link:RelNotes/1.7.0.1.txt[1.7.0.1],
191 link:RelNotes/1.7.0.txt[1.7.0].
e923eaeb 192
1b974346 193* link:v1.6.6.3/git.html[documentation for release 1.6.6.3]
902f2353
JH
194
195* release notes for
1b974346 196 link:RelNotes/1.6.6.3.txt[1.6.6.3],
761e742d
NP
197 link:RelNotes/1.6.6.2.txt[1.6.6.2],
198 link:RelNotes/1.6.6.1.txt[1.6.6.1],
199 link:RelNotes/1.6.6.txt[1.6.6].
902f2353 200
1b974346 201* link:v1.6.5.9/git.html[documentation for release 1.6.5.9]
78d553b7
JH
202
203* release notes for
1b974346 204 link:RelNotes/1.6.5.9.txt[1.6.5.9],
761e742d
NP
205 link:RelNotes/1.6.5.8.txt[1.6.5.8],
206 link:RelNotes/1.6.5.7.txt[1.6.5.7],
207 link:RelNotes/1.6.5.6.txt[1.6.5.6],
208 link:RelNotes/1.6.5.5.txt[1.6.5.5],
209 link:RelNotes/1.6.5.4.txt[1.6.5.4],
210 link:RelNotes/1.6.5.3.txt[1.6.5.3],
211 link:RelNotes/1.6.5.2.txt[1.6.5.2],
212 link:RelNotes/1.6.5.1.txt[1.6.5.1],
213 link:RelNotes/1.6.5.txt[1.6.5].
78d553b7 214
1b974346 215* link:v1.6.4.5/git.html[documentation for release 1.6.4.5]
0a53e9dd
JH
216
217* release notes for
1b974346 218 link:RelNotes/1.6.4.5.txt[1.6.4.5],
761e742d
NP
219 link:RelNotes/1.6.4.4.txt[1.6.4.4],
220 link:RelNotes/1.6.4.3.txt[1.6.4.3],
221 link:RelNotes/1.6.4.2.txt[1.6.4.2],
222 link:RelNotes/1.6.4.1.txt[1.6.4.1],
223 link:RelNotes/1.6.4.txt[1.6.4].
0a53e9dd 224
441b40d8 225* link:v1.6.3.4/git.html[documentation for release 1.6.3.4]
6096d759
JH
226
227* release notes for
761e742d
NP
228 link:RelNotes/1.6.3.4.txt[1.6.3.4],
229 link:RelNotes/1.6.3.3.txt[1.6.3.3],
230 link:RelNotes/1.6.3.2.txt[1.6.3.2],
231 link:RelNotes/1.6.3.1.txt[1.6.3.1],
232 link:RelNotes/1.6.3.txt[1.6.3].
a95148de
JH
233
234* release notes for
761e742d
NP
235 link:RelNotes/1.6.2.5.txt[1.6.2.5],
236 link:RelNotes/1.6.2.4.txt[1.6.2.4],
237 link:RelNotes/1.6.2.3.txt[1.6.2.3],
238 link:RelNotes/1.6.2.2.txt[1.6.2.2],
239 link:RelNotes/1.6.2.1.txt[1.6.2.1],
240 link:RelNotes/1.6.2.txt[1.6.2].
a95148de 241
621f1b4b 242* link:v1.6.1.3/git.html[documentation for release 1.6.1.3]
8104ebfe
JH
243
244* release notes for
761e742d
NP
245 link:RelNotes/1.6.1.3.txt[1.6.1.3],
246 link:RelNotes/1.6.1.2.txt[1.6.1.2],
247 link:RelNotes/1.6.1.1.txt[1.6.1.1],
248 link:RelNotes/1.6.1.txt[1.6.1].
8104ebfe 249
efe05b01 250* link:v1.6.0.6/git.html[documentation for release 1.6.0.6]
ea02eef0
JH
251
252* release notes for
761e742d
NP
253 link:RelNotes/1.6.0.6.txt[1.6.0.6],
254 link:RelNotes/1.6.0.5.txt[1.6.0.5],
255 link:RelNotes/1.6.0.4.txt[1.6.0.4],
256 link:RelNotes/1.6.0.3.txt[1.6.0.3],
257 link:RelNotes/1.6.0.2.txt[1.6.0.2],
258 link:RelNotes/1.6.0.1.txt[1.6.0.1],
259 link:RelNotes/1.6.0.txt[1.6.0].
ea02eef0 260
efe05b01 261* link:v1.5.6.6/git.html[documentation for release 1.5.6.6]
e449f105
JH
262
263* release notes for
761e742d
NP
264 link:RelNotes/1.5.6.6.txt[1.5.6.6],
265 link:RelNotes/1.5.6.5.txt[1.5.6.5],
266 link:RelNotes/1.5.6.4.txt[1.5.6.4],
267 link:RelNotes/1.5.6.3.txt[1.5.6.3],
268 link:RelNotes/1.5.6.2.txt[1.5.6.2],
269 link:RelNotes/1.5.6.1.txt[1.5.6.1],
270 link:RelNotes/1.5.6.txt[1.5.6].
e449f105 271
efe05b01 272* link:v1.5.5.6/git.html[documentation for release 1.5.5.6]
1d2375dd
JH
273
274* release notes for
761e742d
NP
275 link:RelNotes/1.5.5.6.txt[1.5.5.6],
276 link:RelNotes/1.5.5.5.txt[1.5.5.5],
277 link:RelNotes/1.5.5.4.txt[1.5.5.4],
278 link:RelNotes/1.5.5.3.txt[1.5.5.3],
279 link:RelNotes/1.5.5.2.txt[1.5.5.2],
280 link:RelNotes/1.5.5.1.txt[1.5.5.1],
281 link:RelNotes/1.5.5.txt[1.5.5].
1d2375dd 282
efe05b01 283* link:v1.5.4.7/git.html[documentation for release 1.5.4.7]
6ce8e44a
JH
284
285* release notes for
761e742d
NP
286 link:RelNotes/1.5.4.7.txt[1.5.4.7],
287 link:RelNotes/1.5.4.6.txt[1.5.4.6],
288 link:RelNotes/1.5.4.5.txt[1.5.4.5],
289 link:RelNotes/1.5.4.4.txt[1.5.4.4],
290 link:RelNotes/1.5.4.3.txt[1.5.4.3],
291 link:RelNotes/1.5.4.2.txt[1.5.4.2],
292 link:RelNotes/1.5.4.1.txt[1.5.4.1],
293 link:RelNotes/1.5.4.txt[1.5.4].
6ce8e44a 294
e708af6e 295* link:v1.5.3.8/git.html[documentation for release 1.5.3.8]
5587cac2
JH
296
297* release notes for
761e742d
NP
298 link:RelNotes/1.5.3.8.txt[1.5.3.8],
299 link:RelNotes/1.5.3.7.txt[1.5.3.7],
300 link:RelNotes/1.5.3.6.txt[1.5.3.6],
301 link:RelNotes/1.5.3.5.txt[1.5.3.5],
302 link:RelNotes/1.5.3.4.txt[1.5.3.4],
303 link:RelNotes/1.5.3.3.txt[1.5.3.3],
304 link:RelNotes/1.5.3.2.txt[1.5.3.2],
305 link:RelNotes/1.5.3.1.txt[1.5.3.1],
306 link:RelNotes/1.5.3.txt[1.5.3].
b6e4db6a 307
e636106c
JH
308* link:v1.5.2.5/git.html[documentation for release 1.5.2.5]
309
aba170cd 310* release notes for
761e742d
NP
311 link:RelNotes/1.5.2.5.txt[1.5.2.5],
312 link:RelNotes/1.5.2.4.txt[1.5.2.4],
313 link:RelNotes/1.5.2.3.txt[1.5.2.3],
314 link:RelNotes/1.5.2.2.txt[1.5.2.2],
315 link:RelNotes/1.5.2.1.txt[1.5.2.1],
316 link:RelNotes/1.5.2.txt[1.5.2].
aba170cd
JH
317
318* link:v1.5.1.6/git.html[documentation for release 1.5.1.6]
319
320* release notes for
761e742d
NP
321 link:RelNotes/1.5.1.6.txt[1.5.1.6],
322 link:RelNotes/1.5.1.5.txt[1.5.1.5],
323 link:RelNotes/1.5.1.4.txt[1.5.1.4],
324 link:RelNotes/1.5.1.3.txt[1.5.1.3],
325 link:RelNotes/1.5.1.2.txt[1.5.1.2],
326 link:RelNotes/1.5.1.1.txt[1.5.1.1],
327 link:RelNotes/1.5.1.txt[1.5.1].
2ff3f61a
JH
328
329* link:v1.5.0.7/git.html[documentation for release 1.5.0.7]
330
aba170cd 331* release notes for
761e742d
NP
332 link:RelNotes/1.5.0.7.txt[1.5.0.7],
333 link:RelNotes/1.5.0.6.txt[1.5.0.6],
334 link:RelNotes/1.5.0.5.txt[1.5.0.5],
335 link:RelNotes/1.5.0.3.txt[1.5.0.3],
336 link:RelNotes/1.5.0.2.txt[1.5.0.2],
337 link:RelNotes/1.5.0.1.txt[1.5.0.1],
338 link:RelNotes/1.5.0.txt[1.5.0].
2ff3f61a
JH
339
340* documentation for release link:v1.4.4.4/git.html[1.4.4.4],
341 link:v1.3.3/git.html[1.3.3],
342 link:v1.2.6/git.html[1.2.6],
343 link:v1.0.13/git.html[1.0.13].
26cfcfbf
JH
344
345============
346
347endif::stalenotes[]
348
cb22bc44
AE
349OPTIONS
350-------
351--version::
a87cd02c 352 Prints the git suite version that the 'git' program came from.
cb22bc44
AE
353
354--help::
a87cd02c 355 Prints the synopsis and a list of the most commonly used
0f6f195b
CC
356 commands. If the option '--all' or '-a' is given then all
357 available commands are printed. If a git command is named this
358 option will bring up the manual page for that command.
45533d26
CC
359+
360Other options are available to control how the manual page is
5162e697 361displayed. See linkgit:git-help[1] for more information,
db5d6666
JN
362because `git --help ...` is converted internally into `git
363help ...`.
cb22bc44 364
8b1fa778
AR
365-c <name>=<value>::
366 Pass a configuration parameter to the command. The value
367 given will override values from configuration files.
368 The <name> is expected in the same format as listed by
369 'git config' (subkeys separated by dots).
370
62b4698e 371--exec-path[=<path>]::
a87cd02c 372 Path to wherever your core git programs are installed.
cb22bc44 373 This can also be controlled by setting the GIT_EXEC_PATH
56992f76 374 environment variable. If no path is given, 'git' will print
cb22bc44
AE
375 the current setting and then exit.
376
89a56bfb 377--html-path::
239b5ed9
JN
378 Print the path, without trailing slash, where git's HTML
379 documentation is installed and exit.
89a56bfb 380
f2dd8c37 381--man-path::
239b5ed9
JN
382 Print the manpath (see `man(1)`) for the man pages for
383 this version of git and exit.
f2dd8c37
JS
384
385--info-path::
239b5ed9
JN
386 Print the path where the Info files documenting this
387 version of git are installed and exit.
89a56bfb 388
3240240f
SB
389-p::
390--paginate::
06300d97
JN
391 Pipe all output into 'less' (or if set, $PAGER) if standard
392 output is a terminal. This overrides the `pager.<cmd>`
393 configuration options (see the "Configuration Mechanism" section
394 below).
6acbcb92 395
463a849d
MM
396--no-pager::
397 Do not pipe git output into a pager.
398
6acbcb92
JS
399--git-dir=<path>::
400 Set the path to the repository. This can also be controlled by
302cc11a
LY
401 setting the GIT_DIR environment variable. It can be an absolute
402 path or relative path to current working directory.
6acbcb92 403
892c41b9 404--work-tree=<path>::
ea472c1e
JH
405 Set the path to the working tree. It can be an absolute path
406 or a path relative to the current working directory.
892c41b9
ML
407 This can also be controlled by setting the GIT_WORK_TREE
408 environment variable and the core.worktree configuration
ea472c1e
JH
409 variable (see core.worktree in linkgit:git-config[1] for a
410 more detailed discussion).
892c41b9 411
d49483f0
JT
412--namespace=<path>::
413 Set the git namespace. See linkgit:gitnamespaces[7] for more
414 details. Equivalent to setting the `GIT_NAMESPACE` environment
415 variable.
416
6acbcb92 417--bare::
9277d602
JH
418 Treat the repository as a bare repository. If GIT_DIR
419 environment is not set, it is set to the current working
420 directory.
421
b0fa7ab5
CC
422--no-replace-objects::
423 Do not use replacement refs to replace git objects. See
424 linkgit:git-replace[1] for more information.
425
9755afbd 426
23091e95
BF
427GIT COMMANDS
428------------
9755afbd 429
23091e95
BF
430We divide git into high level ("porcelain") commands and low level
431("plumbing") commands.
8b15e2fb 432
23091e95
BF
433High-level commands (porcelain)
434-------------------------------
435
436We separate the porcelain commands into the main commands and some
437ancillary user utilities.
438
439Main porcelain commands
440~~~~~~~~~~~~~~~~~~~~~~~
905197de 441
377e8139 442include::cmds-mainporcelain.txt[]
e31bb3bb 443
90933efb 444Ancillary Commands
23091e95 445~~~~~~~~~~~~~~~~~~
2f2de9b4
JH
446Manipulators:
447
377e8139 448include::cmds-ancillarymanipulators.txt[]
204ee6a9 449
90933efb 450Interrogators:
204ee6a9 451
377e8139 452include::cmds-ancillaryinterrogators.txt[]
7fc9d69f 453
89bf2077
JH
454
455Interacting with Others
456~~~~~~~~~~~~~~~~~~~~~~~
457
458These commands are to interact with foreign SCM and with other
459people via patch over e-mail.
460
461include::cmds-foreignscminterface.txt[]
462
463
b1f33d62
RR
464Low-level commands (plumbing)
465-----------------------------
466
467Although git includes its
468own porcelain layer, its low-level commands are sufficient to support
469development of alternative porcelains. Developers of such porcelains
5162e697
DM
470might start by reading about linkgit:git-update-index[1] and
471linkgit:git-read-tree[1].
b1f33d62 472
89bf2077
JH
473The interface (input, output, set of options and the semantics)
474to these low-level commands are meant to be a lot more stable
475than Porcelain level commands, because these commands are
476primarily for scripted use. The interface to Porcelain commands
477on the other hand are subject to change in order to improve the
478end user experience.
479
480The following description divides
481the low-level commands into commands that manipulate objects (in
b1f33d62
RR
482the repository, index, and working tree), commands that interrogate and
483compare objects, and commands that move objects and references between
484repositories.
485
89bf2077 486
b1f33d62
RR
487Manipulation commands
488~~~~~~~~~~~~~~~~~~~~~
b1f33d62 489
377e8139 490include::cmds-plumbingmanipulators.txt[]
b1f33d62
RR
491
492
493Interrogation commands
494~~~~~~~~~~~~~~~~~~~~~~
495
377e8139 496include::cmds-plumbinginterrogators.txt[]
b1f33d62
RR
497
498In general, the interrogate commands do not touch the files in
499the working tree.
500
501
502Synching repositories
503~~~~~~~~~~~~~~~~~~~~~
504
377e8139 505include::cmds-synchingrepositories.txt[]
b1f33d62 506
57f6ec02 507The following are helper commands used by the above; end users
89bf2077
JH
508typically do not use them directly.
509
510include::cmds-synchelpers.txt[]
511
512
513Internal helper commands
514~~~~~~~~~~~~~~~~~~~~~~~~
515
516These are internal helper commands used by other commands; end
517users typically do not use them directly.
518
519include::cmds-purehelpers.txt[]
520
b1f33d62 521
5773c9f2
JH
522Configuration Mechanism
523-----------------------
524
2fa090b6 525Starting from 0.99.9 (actually mid 0.99.8.GIT), `.git/config` file
5773c9f2 526is used to hold per-repository configuration options. It is a
addf88e4 527simple text file modeled after `.ini` format familiar to some
5773c9f2
JH
528people. Here is an example:
529
530------------
531#
2fa090b6 532# A '#' or ';' character indicates a comment.
5773c9f2
JH
533#
534
535; core variables
536[core]
537 ; Don't trust file modes
538 filemode = false
539
540; user identity
541[user]
542 name = "Junio C Hamano"
543 email = "junkio@twinsun.com"
544
545------------
546
547Various commands read from the configuration file and adjust
06300d97
JN
548their operation accordingly. See linkgit:git-config[1] for a
549list.
5773c9f2
JH
550
551
6c84e2e0 552Identifier Terminology
2cf565c5
DG
553----------------------
554<object>::
2fa090b6 555 Indicates the object name for any type of object.
2cf565c5
DG
556
557<blob>::
2fa090b6 558 Indicates a blob object name.
2cf565c5
DG
559
560<tree>::
2fa090b6 561 Indicates a tree object name.
2cf565c5
DG
562
563<commit>::
2fa090b6 564 Indicates a commit object name.
2cf565c5
DG
565
566<tree-ish>::
2fa090b6 567 Indicates a tree, commit or tag object name. A
6c84e2e0
DG
568 command that takes a <tree-ish> argument ultimately wants to
569 operate on a <tree> object but automatically dereferences
570 <commit> and <tag> objects that point at a <tree>.
2cf565c5 571
043d7605
TT
572<commit-ish>::
573 Indicates a commit or tag object name. A
574 command that takes a <commit-ish> argument ultimately wants to
575 operate on a <commit> object but automatically dereferences
576 <tag> objects that point at a <commit>.
577
2cf565c5
DG
578<type>::
579 Indicates that an object type is required.
2fa090b6 580 Currently one of: `blob`, `tree`, `commit`, or `tag`.
2cf565c5
DG
581
582<file>::
2fa090b6
JH
583 Indicates a filename - almost always relative to the
584 root of the tree structure `GIT_INDEX_FILE` describes.
2cf565c5 585
c1bdacf9
DG
586Symbolic Identifiers
587--------------------
90933efb 588Any git command accepting any <object> can also use the following
6c84e2e0 589symbolic notation:
c1bdacf9
DG
590
591HEAD::
0abcfbff 592 indicates the head of the current branch.
2fa090b6 593
c1bdacf9 594<tag>::
2fa090b6 595 a valid tag 'name'
0abcfbff 596 (i.e. a `refs/tags/<tag>` reference).
2fa090b6 597
c1bdacf9 598<head>::
2fa090b6 599 a valid head 'name'
0abcfbff 600 (i.e. a `refs/heads/<head>` reference).
2fa090b6 601
d47107d8 602For a more complete list of ways to spell object names, see
9d83e382 603"SPECIFYING REVISIONS" section in linkgit:gitrevisions[7].
d47107d8 604
c1bdacf9
DG
605
606File/Directory Structure
607------------------------
c1bdacf9 608
6998e4db 609Please see the linkgit:gitrepository-layout[5] document.
c1bdacf9 610
6998e4db 611Read linkgit:githooks[5] for more details about each hook.
6250ad1e 612
c1bdacf9 613Higher level SCMs may provide and manage additional information in the
2fa090b6 614`$GIT_DIR`.
c1bdacf9 615
a1d4aa74 616
2cf565c5
DG
617Terminology
618-----------
6998e4db 619Please see linkgit:gitglossary[7].
2cf565c5
DG
620
621
622Environment Variables
623---------------------
624Various git commands use the following environment variables:
625
c1bdacf9
DG
626The git Repository
627~~~~~~~~~~~~~~~~~~
628These environment variables apply to 'all' core git commands. Nb: it
629is worth noting that they may be used/overridden by SCMS sitting above
2fa090b6 630git so take care if using Cogito etc.
c1bdacf9
DG
631
632'GIT_INDEX_FILE'::
633 This environment allows the specification of an alternate
5f3aa197
LS
634 index file. If not specified, the default of `$GIT_DIR/index`
635 is used.
c1bdacf9
DG
636
637'GIT_OBJECT_DIRECTORY'::
638 If the object storage directory is specified via this
639 environment variable then the sha1 directories are created
640 underneath - otherwise the default `$GIT_DIR/objects`
641 directory is used.
642
643'GIT_ALTERNATE_OBJECT_DIRECTORIES'::
644 Due to the immutable nature of git objects, old objects can be
645 archived into shared, read-only directories. This variable
80ba074f
JS
646 specifies a ":" separated (on Windows ";" separated) list
647 of git object directories which can be used to search for git
648 objects. New objects will not be written to these directories.
c1bdacf9
DG
649
650'GIT_DIR'::
2fa090b6
JH
651 If the 'GIT_DIR' environment variable is set then it
652 specifies a path to use instead of the default `.git`
653 for the base of the repository.
75940a00 654 The '--git-dir' command-line option also sets this value.
c1bdacf9 655
892c41b9
ML
656'GIT_WORK_TREE'::
657 Set the path to the working tree. The value will not be
658 used in combination with repositories found automatically in
659 a .git directory (i.e. $GIT_DIR is not set).
660 This can also be controlled by the '--work-tree' command line
661 option and the core.worktree configuration variable.
662
d49483f0
JT
663'GIT_NAMESPACE'::
664 Set the git namespace; see linkgit:gitnamespaces[7] for details.
665 The '--namespace' command-line option also sets this value.
666
0454dd93
DR
667'GIT_CEILING_DIRECTORIES'::
668 This should be a colon-separated list of absolute paths.
669 If set, it is a list of directories that git should not chdir
670 up into while looking for a repository directory.
671 It will not exclude the current working directory or
672 a GIT_DIR set on the command line or in the environment.
673 (Useful for excluding slow-loading network directories.)
674
cf87463e 675'GIT_DISCOVERY_ACROSS_FILESYSTEM'::
e6405517
JH
676 When run in a directory that does not have ".git" repository
677 directory, git tries to find such a directory in the parent
678 directories to find the top of the working tree, but by default it
679 does not cross filesystem boundaries. This environment variable
cf87463e
JH
680 can be set to true to tell git not to stop at filesystem
681 boundaries. Like 'GIT_CEILING_DIRECTORIES', this will not affect
682 an explicit repository directory set via 'GIT_DIR' or on the
683 command line.
8030e442 684
c1bdacf9
DG
685git Commits
686~~~~~~~~~~~
687'GIT_AUTHOR_NAME'::
688'GIT_AUTHOR_EMAIL'::
689'GIT_AUTHOR_DATE'::
690'GIT_COMMITTER_NAME'::
691'GIT_COMMITTER_EMAIL'::
4e58bf97 692'GIT_COMMITTER_DATE'::
28a94f88 693'EMAIL'::
5162e697 694 see linkgit:git-commit-tree[1]
c1bdacf9
DG
695
696git Diffs
697~~~~~~~~~
d81ed1b5 698'GIT_DIFF_OPTS'::
fde97d8a
SE
699 Only valid setting is "--unified=??" or "-u??" to set the
700 number of context lines shown when a unified diff is created.
701 This takes precedence over any "-U" or "--unified" option
702 value passed on the git diff command line.
703
d81ed1b5 704'GIT_EXTERNAL_DIFF'::
fde97d8a
SE
705 When the environment variable 'GIT_EXTERNAL_DIFF' is set, the
706 program named by it is called, instead of the diff invocation
707 described above. For a path that is added, removed, or modified,
708 'GIT_EXTERNAL_DIFF' is called with 7 parameters:
709
710 path old-file old-hex old-mode new-file new-hex new-mode
711+
712where:
713
714 <old|new>-file:: are files GIT_EXTERNAL_DIFF can use to read the
715 contents of <old|new>,
716 <old|new>-hex:: are the 40-hexdigit SHA1 hashes,
717 <old|new>-mode:: are the octal representation of the file modes.
fde97d8a
SE
718+
719The file parameters can point at the user's working file
720(e.g. `new-file` in "git-diff-files"), `/dev/null` (e.g. `old-file`
721when a new file is added), or a temporary file (e.g. `old-file` in the
722index). 'GIT_EXTERNAL_DIFF' should not worry about unlinking the
723temporary file --- it is removed when 'GIT_EXTERNAL_DIFF' exits.
724+
725For a path that is unmerged, 'GIT_EXTERNAL_DIFF' is called with 1
726parameter, <path>.
2cf565c5 727
575ba9d6
ML
728other
729~~~~~
dbddb714
JN
730'GIT_MERGE_VERBOSITY'::
731 A number controlling the amount of output shown by
732 the recursive merge strategy. Overrides merge.verbosity.
5162e697 733 See linkgit:git-merge[1]
dbddb714 734
c27d205a 735'GIT_PAGER'::
a7738c77
SG
736 This environment variable overrides `$PAGER`. If it is set
737 to an empty string or to the value "cat", git will not launch
ab54cd6c
JN
738 a pager. See also the `core.pager` option in
739 linkgit:git-config[1].
c27d205a 740
36384c97
RSM
741'GIT_EDITOR'::
742 This environment variable overrides `$EDITOR` and `$VISUAL`.
b4ab1980 743 It is used by several git commands when, on interactive mode,
36384c97
RSM
744 an editor is to be launched. See also linkgit:git-var[1]
745 and the `core.editor` option in linkgit:git-config[1].
746
d5538b41 747'GIT_SSH'::
0b444cdb
TR
748 If this environment variable is set then 'git fetch'
749 and 'git push' will use this command instead
2fd02c92 750 of 'ssh' when they need to connect to a remote system.
483bc4f0 751 The '$GIT_SSH' command will be given exactly two arguments:
d5538b41
SP
752 the 'username@host' (or just 'host') from the URL and the
753 shell command to execute on that remote system.
754+
755To pass options to the program that you want to list in GIT_SSH
756you will need to wrap the program and options into a shell script,
757then set GIT_SSH to refer to the shell script.
758+
759Usually it is easier to configure any desired options through your
760personal `.ssh/config` file. Please consult your ssh documentation
761for further details.
762
453842c9
KF
763'GIT_ASKPASS'::
764 If this environment variable is set, then git commands which need to
765 acquire passwords or passphrases (e.g. for HTTP or IMAP authentication)
766 will call this program with a suitable prompt as command line argument
767 and read the password from its STDOUT. See also the 'core.askpass'
768 option in linkgit:git-config[1].
769
06f59e9f
TT
770'GIT_FLUSH'::
771 If this environment variable is set to "1", then commands such
0b444cdb
TR
772 as 'git blame' (in incremental mode), 'git rev-list', 'git log',
773 and 'git whatchanged' will force a flush of the output stream
06f59e9f
TT
774 after each commit-oriented record have been flushed. If this
775 variable is set to "0", the output of these commands will be done
776 using completely buffered I/O. If this environment variable is
777 not set, git will choose buffered or record-oriented flushing
778 based on whether stdout appears to be redirected to a file or not.
779
575ba9d6 780'GIT_TRACE'::
2886bdb1
CC
781 If this variable is set to "1", "2" or "true" (comparison
782 is case insensitive), git will print `trace:` messages on
575ba9d6
ML
783 stderr telling about alias expansion, built-in command
784 execution and external command execution.
2886bdb1
CC
785 If this variable is set to an integer value greater than 1
786 and lower than 10 (strictly) then git will interpret this
787 value as an open file descriptor and will try to write the
788 trace messages into this file descriptor.
789 Alternatively, if this variable is set to an absolute path
790 (starting with a '/' character), git will interpret this
791 as a file path and will try to write the trace messages
792 into it.
575ba9d6 793
8db9307c
JH
794Discussion[[Discussion]]
795------------------------
40dac517
BF
796
797More detail on the following is available from the
798link:user-manual.html#git-concepts[git concepts chapter of the
6998e4db 799user-manual] and linkgit:gitcore-tutorial[7].
40dac517
BF
800
801A git project normally consists of a working directory with a ".git"
802subdirectory at the top level. The .git directory contains, among other
803things, a compressed object database representing the complete history
804of the project, an "index" file which links that history to the current
805contents of the working tree, and named pointers into that history such
806as tags and branch heads.
807
808The object database contains objects of three main types: blobs, which
809hold file data; trees, which point to blobs and other trees to build up
02ff6250 810directory hierarchies; and commits, which each reference a single tree
40dac517
BF
811and some number of parent commits.
812
813The commit, equivalent to what other systems call a "changeset" or
814"version", represents a step in the project's history, and each parent
815represents an immediately preceding step. Commits with more than one
816parent represent merges of independent lines of development.
817
818All objects are named by the SHA1 hash of their contents, normally
819written as a string of 40 hex digits. Such names are globally unique.
820The entire history leading up to a commit can be vouched for by signing
821just that commit. A fourth object type, the tag, is provided for this
822purpose.
823
824When first created, objects are stored in individual files, but for
825efficiency may later be compressed together into "pack files".
826
827Named pointers called refs mark interesting points in history. A ref
828may contain the SHA1 name of an object or the name of another ref. Refs
829with names beginning `ref/head/` contain the SHA1 name of the most
02ff6250 830recent commit (or "head") of a branch under development. SHA1 names of
40dac517
BF
831tags of interest are stored under `ref/tags/`. A special ref named
832`HEAD` contains the name of the currently checked-out branch.
833
834The index file is initialized with a list of all paths and, for each
835path, a blob object and a set of attributes. The blob object represents
836the contents of the file as of the head of the current branch. The
837attributes (last modified time, size, etc.) are taken from the
838corresponding file in the working tree. Subsequent changes to the
839working tree can be found by comparing these attributes. The index may
840be updated with new content, and new commits may be created from the
841content stored in the index.
842
843The index is also capable of storing multiple entries (called "stages")
844for a given pathname. These stages are used to hold the various
845unmerged version of a file when a merge is in progress.
6c84e2e0 846
7687ae98
JH
847FURTHER DOCUMENTATION
848---------------------
849
850See the references in the "description" section to get started
851using git. The following is probably more detail than necessary
852for a first-time user.
853
854The link:user-manual.html#git-concepts[git concepts chapter of the
855user-manual] and linkgit:gitcore-tutorial[7] both provide
856introductions to the underlying git architecture.
857
858See linkgit:gitworkflows[7] for an overview of recommended workflows.
859
860See also the link:howto-index.html[howto] documents for some useful
861examples.
862
863The internals are documented in the
864link:technical/api-index.html[GIT API documentation].
865
866Users migrating from CVS may also want to
867read linkgit:gitcvs-migration[7].
868
869
cb22bc44
AE
870Authors
871-------
48bb914e
JK
872Git was started by Linus Torvalds, and is currently maintained by Junio
873C Hamano. Numerous contributions have come from the git mailing list
6ecc01f2
JH
874<git@vger.kernel.org>. http://www.ohloh.net/p/git/contributors/summary
875gives you a more complete list of contributors.
876
877If you have a clone of git.git itself, the
d8f708f8
JK
878output of linkgit:git-shortlog[1] and linkgit:git-blame[1] can show you
879the authors for specific parts of the project.
2cf565c5 880
c97ca277
JH
881Reporting Bugs
882--------------
883
884Report bugs to the Git mailing list <git@vger.kernel.org> where the
885development and maintenance is primarily done. You do not have to be
886subscribed to the list to send a message there.
887
497c8331
CC
888SEE ALSO
889--------
890linkgit:gittutorial[7], linkgit:gittutorial-2[7],
5cbef01a 891link:everyday.html[Everyday Git], linkgit:gitcvs-migration[7],
497c8331 892linkgit:gitglossary[7], linkgit:gitcore-tutorial[7],
801a011d
TR
893linkgit:gitcli[7], link:user-manual.html[The Git User's Manual],
894linkgit:gitworkflows[7]
497c8331 895
2cf565c5
DG
896GIT
897---
9e1f0a85 898Part of the linkgit:git[1] suite