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