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