Make git-prune submodule aware (and fix a SEGFAULT in the process)
[git/git.git] / Documentation / git.txt
1 git(7)
2 ======
3
4 NAME
5 ----
6 git - the stupid content tracker
7
8
9 SYNOPSIS
10 --------
11 [verse]
12 'git' [--version] [--exec-path[=GIT_EXEC_PATH]] [-p|--paginate]
13 [--bare] [--git-dir=GIT_DIR] [--help] COMMAND [ARGS]
14
15 DESCRIPTION
16 -----------
17 Git is a fast, scalable, distributed revision control system with an
18 unusually rich command set that provides both high-level operations
19 and full access to internals.
20
21 See this link:tutorial.html[tutorial] to get started, then see
22 link:everyday.html[Everyday Git] for a useful minimum set of commands, and
23 "man git-commandname" for documentation of each command. CVS users may
24 also want to read link:cvs-migration.html[CVS migration]. See
25 link:user-manual.html[Git User's Manual] for a more in-depth
26 introduction.
27
28 The COMMAND is either a name of a Git command (see below) or an alias
29 as defined in the configuration file (see gitlink:git-config[1]).
30
31 Formatted and hyperlinked version of the latest git
32 documentation can be viewed at
33 `http://www.kernel.org/pub/software/scm/git/docs/`.
34
35 ifdef::stalenotes[]
36 [NOTE]
37 ============
38
39 You are reading the documentation for the latest (possibly
40 unreleased) version of git, that is available from 'master'
41 branch of the `git.git` repository.
42 Documentation for older releases are available here:
43
44 * link:v1.5.2/git.html[documentation for release 1.5.2]
45
46 * release notes for
47 link:RelNotes-1.5.2.txt[1.5.2].
48
49 * link:v1.5.1.6/git.html[documentation for release 1.5.1.6]
50
51 * release notes for
52 link:RelNotes-1.5.1.6.txt[1.5.1.6],
53 link:RelNotes-1.5.1.5.txt[1.5.1.5],
54 link:RelNotes-1.5.1.4.txt[1.5.1.4],
55 link:RelNotes-1.5.1.3.txt[1.5.1.3],
56 link:RelNotes-1.5.1.2.txt[1.5.1.2],
57 link:RelNotes-1.5.1.1.txt[1.5.1.1],
58 link:RelNotes-1.5.1.txt[1.5.1].
59
60 * link:v1.5.0.7/git.html[documentation for release 1.5.0.7]
61
62 * release notes for
63 link:RelNotes-1.5.0.7.txt[1.5.0.7],
64 link:RelNotes-1.5.0.6.txt[1.5.0.6],
65 link:RelNotes-1.5.0.5.txt[1.5.0.5],
66 link:RelNotes-1.5.0.3.txt[1.5.0.3],
67 link:RelNotes-1.5.0.2.txt[1.5.0.2],
68 link:RelNotes-1.5.0.1.txt[1.5.0.1],
69 link:RelNotes-1.5.0.txt[1.5.0].
70
71 * documentation for release link:v1.4.4.4/git.html[1.4.4.4],
72 link:v1.3.3/git.html[1.3.3],
73 link:v1.2.6/git.html[1.2.6],
74 link:v1.0.13/git.html[1.0.13].
75
76 ============
77
78 endif::stalenotes[]
79
80 OPTIONS
81 -------
82 --version::
83 Prints the git suite version that the 'git' program came from.
84
85 --help::
86 Prints the synopsis and a list of the most commonly used
87 commands. If a git command is named this option will bring up
88 the man-page for that command. If the option '--all' or '-a' is
89 given then all available commands are printed.
90
91 --exec-path::
92 Path to wherever your core git programs are installed.
93 This can also be controlled by setting the GIT_EXEC_PATH
94 environment variable. If no path is given 'git' will print
95 the current setting and then exit.
96
97 -p|--paginate::
98 Pipe all output into 'less' (or if set, $PAGER).
99
100 --git-dir=<path>::
101 Set the path to the repository. This can also be controlled by
102 setting the GIT_DIR environment variable.
103
104 --bare::
105 Same as --git-dir=`pwd`.
106
107 FURTHER DOCUMENTATION
108 ---------------------
109
110 See the references above to get started using git. The following is
111 probably more detail than necessary for a first-time user.
112
113 The <<Discussion,Discussion>> section below and the
114 link:core-tutorial.html[Core tutorial] both provide introductions to the
115 underlying git architecture.
116
117 See also the link:howto-index.html[howto] documents for some useful
118 examples.
119
120 GIT COMMANDS
121 ------------
122
123 We divide git into high level ("porcelain") commands and low level
124 ("plumbing") commands.
125
126 High-level commands (porcelain)
127 -------------------------------
128
129 We separate the porcelain commands into the main commands and some
130 ancillary user utilities.
131
132 Main porcelain commands
133 ~~~~~~~~~~~~~~~~~~~~~~~
134
135 include::cmds-mainporcelain.txt[]
136
137 Ancillary Commands
138 ~~~~~~~~~~~~~~~~~~
139 Manipulators:
140
141 include::cmds-ancillarymanipulators.txt[]
142
143 Interrogators:
144
145 include::cmds-ancillaryinterrogators.txt[]
146
147
148 Interacting with Others
149 ~~~~~~~~~~~~~~~~~~~~~~~
150
151 These commands are to interact with foreign SCM and with other
152 people via patch over e-mail.
153
154 include::cmds-foreignscminterface.txt[]
155
156
157 Low-level commands (plumbing)
158 -----------------------------
159
160 Although git includes its
161 own porcelain layer, its low-level commands are sufficient to support
162 development of alternative porcelains. Developers of such porcelains
163 might start by reading about gitlink:git-update-index[1] and
164 gitlink:git-read-tree[1].
165
166 The interface (input, output, set of options and the semantics)
167 to these low-level commands are meant to be a lot more stable
168 than Porcelain level commands, because these commands are
169 primarily for scripted use. The interface to Porcelain commands
170 on the other hand are subject to change in order to improve the
171 end user experience.
172
173 The following description divides
174 the low-level commands into commands that manipulate objects (in
175 the repository, index, and working tree), commands that interrogate and
176 compare objects, and commands that move objects and references between
177 repositories.
178
179
180 Manipulation commands
181 ~~~~~~~~~~~~~~~~~~~~~
182
183 include::cmds-plumbingmanipulators.txt[]
184
185
186 Interrogation commands
187 ~~~~~~~~~~~~~~~~~~~~~~
188
189 include::cmds-plumbinginterrogators.txt[]
190
191 In general, the interrogate commands do not touch the files in
192 the working tree.
193
194
195 Synching repositories
196 ~~~~~~~~~~~~~~~~~~~~~
197
198 include::cmds-synchingrepositories.txt[]
199
200 The following are helper programs used by the above; end users
201 typically do not use them directly.
202
203 include::cmds-synchelpers.txt[]
204
205
206 Internal helper commands
207 ~~~~~~~~~~~~~~~~~~~~~~~~
208
209 These are internal helper commands used by other commands; end
210 users typically do not use them directly.
211
212 include::cmds-purehelpers.txt[]
213
214
215 Configuration Mechanism
216 -----------------------
217
218 Starting from 0.99.9 (actually mid 0.99.8.GIT), `.git/config` file
219 is used to hold per-repository configuration options. It is a
220 simple text file modeled after `.ini` format familiar to some
221 people. Here is an example:
222
223 ------------
224 #
225 # A '#' or ';' character indicates a comment.
226 #
227
228 ; core variables
229 [core]
230 ; Don't trust file modes
231 filemode = false
232
233 ; user identity
234 [user]
235 name = "Junio C Hamano"
236 email = "junkio@twinsun.com"
237
238 ------------
239
240 Various commands read from the configuration file and adjust
241 their operation accordingly.
242
243
244 Identifier Terminology
245 ----------------------
246 <object>::
247 Indicates the object name for any type of object.
248
249 <blob>::
250 Indicates a blob object name.
251
252 <tree>::
253 Indicates a tree object name.
254
255 <commit>::
256 Indicates a commit object name.
257
258 <tree-ish>::
259 Indicates a tree, commit or tag object name. A
260 command that takes a <tree-ish> argument ultimately wants to
261 operate on a <tree> object but automatically dereferences
262 <commit> and <tag> objects that point at a <tree>.
263
264 <commit-ish>::
265 Indicates a commit or tag object name. A
266 command that takes a <commit-ish> argument ultimately wants to
267 operate on a <commit> object but automatically dereferences
268 <tag> objects that point at a <commit>.
269
270 <type>::
271 Indicates that an object type is required.
272 Currently one of: `blob`, `tree`, `commit`, or `tag`.
273
274 <file>::
275 Indicates a filename - almost always relative to the
276 root of the tree structure `GIT_INDEX_FILE` describes.
277
278 Symbolic Identifiers
279 --------------------
280 Any git command accepting any <object> can also use the following
281 symbolic notation:
282
283 HEAD::
284 indicates the head of the current branch (i.e. the
285 contents of `$GIT_DIR/HEAD`).
286
287 <tag>::
288 a valid tag 'name'
289 (i.e. the contents of `$GIT_DIR/refs/tags/<tag>`).
290
291 <head>::
292 a valid head 'name'
293 (i.e. the contents of `$GIT_DIR/refs/heads/<head>`).
294
295 For a more complete list of ways to spell object names, see
296 "SPECIFYING REVISIONS" section in gitlink:git-rev-parse[1].
297
298
299 File/Directory Structure
300 ------------------------
301
302 Please see link:repository-layout.html[repository layout] document.
303
304 Read link:hooks.html[hooks] for more details about each hook.
305
306 Higher level SCMs may provide and manage additional information in the
307 `$GIT_DIR`.
308
309
310 Terminology
311 -----------
312 Please see link:glossary.html[glossary] document.
313
314
315 Environment Variables
316 ---------------------
317 Various git commands use the following environment variables:
318
319 The git Repository
320 ~~~~~~~~~~~~~~~~~~
321 These environment variables apply to 'all' core git commands. Nb: it
322 is worth noting that they may be used/overridden by SCMS sitting above
323 git so take care if using Cogito etc.
324
325 'GIT_INDEX_FILE'::
326 This environment allows the specification of an alternate
327 index file. If not specified, the default of `$GIT_DIR/index`
328 is used.
329
330 'GIT_OBJECT_DIRECTORY'::
331 If the object storage directory is specified via this
332 environment variable then the sha1 directories are created
333 underneath - otherwise the default `$GIT_DIR/objects`
334 directory is used.
335
336 'GIT_ALTERNATE_OBJECT_DIRECTORIES'::
337 Due to the immutable nature of git objects, old objects can be
338 archived into shared, read-only directories. This variable
339 specifies a ":" separated list of git object directories which
340 can be used to search for git objects. New objects will not be
341 written to these directories.
342
343 'GIT_DIR'::
344 If the 'GIT_DIR' environment variable is set then it
345 specifies a path to use instead of the default `.git`
346 for the base of the repository.
347
348 git Commits
349 ~~~~~~~~~~~
350 'GIT_AUTHOR_NAME'::
351 'GIT_AUTHOR_EMAIL'::
352 'GIT_AUTHOR_DATE'::
353 'GIT_COMMITTER_NAME'::
354 'GIT_COMMITTER_EMAIL'::
355 'GIT_COMMITTER_DATE'::
356 'EMAIL'::
357 see gitlink:git-commit-tree[1]
358
359 git Diffs
360 ~~~~~~~~~
361 'GIT_DIFF_OPTS'::
362 Only valid setting is "--unified=??" or "-u??" to set the
363 number of context lines shown when a unified diff is created.
364 This takes precedence over any "-U" or "--unified" option
365 value passed on the git diff command line.
366
367 'GIT_EXTERNAL_DIFF'::
368 When the environment variable 'GIT_EXTERNAL_DIFF' is set, the
369 program named by it is called, instead of the diff invocation
370 described above. For a path that is added, removed, or modified,
371 'GIT_EXTERNAL_DIFF' is called with 7 parameters:
372
373 path old-file old-hex old-mode new-file new-hex new-mode
374 +
375 where:
376
377 <old|new>-file:: are files GIT_EXTERNAL_DIFF can use to read the
378 contents of <old|new>,
379 <old|new>-hex:: are the 40-hexdigit SHA1 hashes,
380 <old|new>-mode:: are the octal representation of the file modes.
381
382 +
383 The file parameters can point at the user's working file
384 (e.g. `new-file` in "git-diff-files"), `/dev/null` (e.g. `old-file`
385 when a new file is added), or a temporary file (e.g. `old-file` in the
386 index). 'GIT_EXTERNAL_DIFF' should not worry about unlinking the
387 temporary file --- it is removed when 'GIT_EXTERNAL_DIFF' exits.
388 +
389 For a path that is unmerged, 'GIT_EXTERNAL_DIFF' is called with 1
390 parameter, <path>.
391
392 other
393 ~~~~~
394 'GIT_PAGER'::
395 This environment variable overrides `$PAGER`.
396
397 'GIT_TRACE'::
398 If this variable is set to "1", "2" or "true" (comparison
399 is case insensitive), git will print `trace:` messages on
400 stderr telling about alias expansion, built-in command
401 execution and external command execution.
402 If this variable is set to an integer value greater than 1
403 and lower than 10 (strictly) then git will interpret this
404 value as an open file descriptor and will try to write the
405 trace messages into this file descriptor.
406 Alternatively, if this variable is set to an absolute path
407 (starting with a '/' character), git will interpret this
408 as a file path and will try to write the trace messages
409 into it.
410
411 Discussion[[Discussion]]
412 ------------------------
413 include::core-intro.txt[]
414
415 Authors
416 -------
417 * git's founding father is Linus Torvalds <torvalds@osdl.org>.
418 * The current git nurse is Junio C Hamano <junkio@cox.net>.
419 * The git potty was written by Andres Ericsson <ae@op5.se>.
420 * General upbringing is handled by the git-list <git@vger.kernel.org>.
421
422 Documentation
423 --------------
424 The documentation for git suite was started by David Greaves
425 <david@dgreaves.com>, and later enhanced greatly by the
426 contributors on the git-list <git@vger.kernel.org>.
427
428 GIT
429 ---
430 Part of the gitlink:git[7] suite
431