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