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