git-commit: log parameter updates.
[git/git.git] / Documentation / git.txt
CommitLineData
7984eabe 1git(7)
2cf565c5 2======
6c84e2e0 3May 2005
2cf565c5
DG
4
5NAME
6----
7git - the stupid content tracker
8
9
10SYNOPSIS
11--------
12'git-<command>' <args>
13
14DESCRIPTION
15-----------
16
17This is reference information for the core git commands.
18
6c84e2e0
DG
19The Discussion section below contains much useful definition and
20clarification info - read that first. And of the commands, I suggest
21reading link:git-update-cache.html[git-update-cache] and
22link:git-read-tree.html[git-read-tree] first - I wish I had!
2cf565c5
DG
23
24David Greaves <david@dgreaves.com>
2508/05/05
26
27Updated by Junio C Hamano <junkio@cox.net> on 2005-05-05 to
28reflect recent changes.
29
30Commands Overview
31-----------------
32The git commands can helpfully be split into those that manipulate
2f2de9b4
JH
33the repository, the cache and the working fileset, those that
34interrogate and compare them, and those that moves objects and
35references between repositories.
2cf565c5 36
204ee6a9
DG
37There are also some ancilliary programs that can be viewed as useful
38aids for using the core commands but which are unlikely to be used by
39SCMs layered over git.
40
2cf565c5
DG
41Manipulation commands
42~~~~~~~~~~~~~~~~~~~~~
2cf565c5
DG
43link:git-checkout-cache.html[git-checkout-cache]::
44 Copy files from the cache to the working directory
45
46link:git-commit-tree.html[git-commit-tree]::
47 Creates a new commit object
48
2cf565c5
DG
49link:git-init-db.html[git-init-db]::
50 Creates an empty git object database
51
2cf565c5
DG
52link:git-merge-base.html[git-merge-base]::
53 Finds as good a common ancestor as possible for a merge
54
2cf565c5
DG
55link:git-mktag.html[git-mktag]::
56 Creates a tag object
57
2cf565c5
DG
58link:git-read-tree.html[git-read-tree]::
59 Reads tree information into the directory cache
60
2cf565c5
DG
61link:git-update-cache.html[git-update-cache]::
62 Modifies the index or directory cache
63
7672db20
BL
64link:git-hash-object.html[git-hash-object]::
65 Computes the object ID from a file.
2cf565c5
DG
66
67link:git-write-tree.html[git-write-tree]::
68 Creates a tree from the current cache
69
70Interrogation commands
71~~~~~~~~~~~~~~~~~~~~~~
72link:git-cat-file.html[git-cat-file]::
73 Provide content or type information for repository objects
74
2cf565c5
DG
75link:git-diff-cache.html[git-diff-cache]::
76 Compares content and mode of blobs between the cache and repository
77
78link:git-diff-files.html[git-diff-files]::
79 Compares files in the working tree and the cache
80
81link:git-diff-tree.html[git-diff-tree]::
82 Compares the content and mode of blobs found via two tree objects
83
2cf565c5
DG
84link:git-export.html[git-export]::
85 Exports each commit and a diff against each of its parents
86
87link:git-fsck-cache.html[git-fsck-cache]::
88 Verifies the connectivity and validity of the objects in the database
89
90link:git-ls-files.html[git-ls-files]::
91 Information about files in the cache/working directory
92
93link:git-ls-tree.html[git-ls-tree]::
94 Displays a tree object in human readable form
95
96link:git-merge-cache.html[git-merge-cache]::
97 Runs a merge for files needing merging
98
99link:git-rev-list.html[git-rev-list]::
100 Lists commit objects in reverse chronological order
101
102link:git-rev-tree.html[git-rev-tree]::
103 Provides the revision tree for one or more commits
104
2cf565c5
DG
105link:git-tar-tree.html[git-tar-tree]::
106 Creates a tar archive of the files in the named tree
107
108link:git-unpack-file.html[git-unpack-file]::
109 Creates a temporary file with a blob's contents
110
aed022ab
EB
111link:git-var.html[git-var]::
112 Displays a git logical variable
113
f9253394
JH
114link:git-verify-pack.html[git-verify-pack]::
115 Validates packed GIT archive files
116
2cf565c5
DG
117The interrogate commands may create files - and you can force them to
118touch the working file set - but in general they don't
119
120
0c04094b
JH
121Synching repositories
122~~~~~~~~~~~~~~~~~~~~~
123
6ec311da
JH
124link:git-clone-script.html[git-clone-script]::
125 Clones a repository into the current repository (user interface)
126
127link:git-clone-pack.html[git-clone-pack]::
128 Clones a repository into the current repository (engine
129 for ssh and local transport)
130
508e67ab
JH
131link:git-fetch-script.html[git-fetch-script]::
132 Download from a remote repository via various protocols
2f2de9b4
JH
133 (user interface).
134
0c04094b 135link:git-pull-script.html[git-pull-script]::
508e67ab 136 Fetch from and merge with a remote repository via
0c04094b
JH
137 various protocols (user interface).
138
204ee6a9
DG
139link:git-http-pull.html[git-http-pull]::
140 Downloads a remote GIT repository via HTTP
141
142link:git-local-pull.html[git-local-pull]::
143 Duplicates another GIT repository on a local system
144
2f2de9b4
JH
145link:git-ssh-pull.html[git-ssh-pull]::
146 Pulls from a remote repository over ssh connection
147
148link:git-send-pack.html[git-send-pack]::
149 Pushes to a remote repository, intelligently.
150
151link:git-receive-pack.html[git-receive-pack]::
152 Invoked by 'git-send-pack' to receive what is pushed to it.
153
154link:git-clone-pack.html[git-clone-pack]::
155 Clones from a remote repository.
156
157link:git-fetch-pack.html[git-fetch-pack]::
158 Updates from a remote repository.
159
508e67ab
JH
160link:git-peek-remote.html[git-peek-remote]::
161 Lists references on a remote repository using upload-pack protocol.
162
2f2de9b4
JH
163link:git-upload-pack.html[git-upload-pack]::
164 Invoked by 'git-clone-pack' and 'git-fetch-pack' to push
165 what are asked for.
166
61e3ef36
JH
167link:git-update-server-info.html[git-update-server-info]::
168 Updates auxiliary information on a dumb server to help
169 clients discover references and packs on it.
170
2f2de9b4
JH
171
172Ancilliary Commands
173-------------------
174Manipulators:
175
176link:git-apply-patch-script.html[git-apply-patch-script]::
177 Sample script to apply the diffs from git-diff-*
178
179link:git-convert-cache.html[git-convert-cache]::
180 Converts old-style GIT repository
181
204ee6a9
DG
182link:git-merge-one-file-script.html[git-merge-one-file-script]::
183 The standard helper program to use with "git-merge-cache"
184
204ee6a9
DG
185link:git-prune-script.html[git-prune-script]::
186 Prunes all unreachable objects from the object database
187
188link:git-resolve-script.html[git-resolve-script]::
189 Script used to merge two trees
190
191link:git-tag-script.html[git-tag-script]::
192 An example script to create a tag object signed with GPG
193
204ee6a9
DG
194
195Interogators:
196
99665af5 197link:git-diff-helper.html[git-diff-helper]::
204ee6a9
DG
198 Generates patch format output for git-diff-*
199
418aaf84
JH
200link:git-ssh-push.html[git-ssh-push]::
201 Helper "server-side" program used by git-ssh-pull
204ee6a9
DG
202
203
204
6c84e2e0 205Identifier Terminology
2cf565c5
DG
206----------------------
207<object>::
6c84e2e0 208 Indicates the sha1 identifier for any type of object
2cf565c5
DG
209
210<blob>::
211 Indicates a blob object sha1 identifier
212
213<tree>::
214 Indicates a tree object sha1 identifier
215
216<commit>::
217 Indicates a commit object sha1 identifier
218
219<tree-ish>::
6c84e2e0
DG
220 Indicates a tree, commit or tag object sha1 identifier. A
221 command that takes a <tree-ish> argument ultimately wants to
222 operate on a <tree> object but automatically dereferences
223 <commit> and <tag> objects that point at a <tree>.
2cf565c5
DG
224
225<type>::
226 Indicates that an object type is required.
227 Currently one of: blob/tree/commit/tag
228
229<file>::
230 Indicates a filename - always relative to the root of
231 the tree structure GIT_INDEX_FILE describes.
232
c1bdacf9
DG
233Symbolic Identifiers
234--------------------
6c84e2e0
DG
235Any git comand accepting any <object> can also use the following
236symbolic notation:
c1bdacf9
DG
237
238HEAD::
6c84e2e0
DG
239 indicates the head of the repository (ie the contents of
240 `$GIT_DIR/HEAD`)
c1bdacf9
DG
241<tag>::
242 a valid tag 'name'+
243 (ie the contents of `$GIT_DIR/refs/tags/<tag>`)
244<head>::
245 a valid head 'name'+
246 (ie the contents of `$GIT_DIR/refs/heads/<head>`)
247<snap>::
248 a valid snapshot 'name'+
249 (ie the contents of `$GIT_DIR/refs/snap/<snap>`)
250
251
252File/Directory Structure
253------------------------
254The git-core manipulates the following areas in the directory:
255
256 .git/ The base (overridden with $GIT_DIR)
257 objects/ The object base (overridden with $GIT_OBJECT_DIRECTORY)
2f2de9b4
JH
258 ??/ 'First 2 chars of object' directories.
259 pack/ Packed archives.
c1bdacf9
DG
260
261 refs/ Directories containing symbolic names for objects
262 (each file contains the hex SHA1 + newline)
263 heads/ Commits which are heads of various sorts
264 tags/ Tags, by the tag name (or some local renaming of it)
2f2de9b4
JH
265 */ Any other subdirectory of refs/ can be used to store
266 files similar to what are under refs/heads/.
267 HEAD Symlink to refs/heads/<current-branch-name>
c1bdacf9
DG
268
269Higher level SCMs may provide and manage additional information in the
270GIT_DIR.
271
2cf565c5
DG
272Terminology
273-----------
6c84e2e0 274Each line contains terms which you may see used interchangeably
2cf565c5
DG
275
276 object database, .git directory
277 directory cache, index
278 id, sha1, sha1-id, sha1 hash
279 type, tag
2cf565c5
DG
280
281
282Environment Variables
283---------------------
284Various git commands use the following environment variables:
285
c1bdacf9
DG
286The git Repository
287~~~~~~~~~~~~~~~~~~
288These environment variables apply to 'all' core git commands. Nb: it
289is worth noting that they may be used/overridden by SCMS sitting above
290git so take care if using Cogito etc
291
292'GIT_INDEX_FILE'::
293 This environment allows the specification of an alternate
294 cache/index file. If not specified, the default of
295 `$GIT_DIR/index` is used.
296
297'GIT_OBJECT_DIRECTORY'::
298 If the object storage directory is specified via this
299 environment variable then the sha1 directories are created
300 underneath - otherwise the default `$GIT_DIR/objects`
301 directory is used.
302
303'GIT_ALTERNATE_OBJECT_DIRECTORIES'::
304 Due to the immutable nature of git objects, old objects can be
305 archived into shared, read-only directories. This variable
306 specifies a ":" seperated list of git object directories which
307 can be used to search for git objects. New objects will not be
308 written to these directories.
309
310'GIT_DIR'::
311 If the 'GIT_DIR' environment variable is set then it specifies
312 a path to use instead of `./.git` for the base of the
313 repository.
314
315git Commits
316~~~~~~~~~~~
317'GIT_AUTHOR_NAME'::
318'GIT_AUTHOR_EMAIL'::
319'GIT_AUTHOR_DATE'::
320'GIT_COMMITTER_NAME'::
321'GIT_COMMITTER_EMAIL'::
322 see link:git-commit-tree.html[git-commit-tree]
323
324git Diffs
325~~~~~~~~~
d81ed1b5
JH
326'GIT_DIFF_OPTS'::
327'GIT_EXTERNAL_DIFF'::
c1bdacf9
DG
328 see the "generating patches" section in :
329 link:git-diff-cache.html[git-diff-cache];
330 link:git-diff-files.html[git-diff-files];
331 link:git-diff-tree.html[git-diff-tree]
2cf565c5 332
6c84e2e0
DG
333Discussion
334----------
335include::../README[]
336
2cf565c5
DG
337Author
338------
6c84e2e0 339Written by Linus Torvalds <torvalds@osdl.org> and the git-list <git@vger.kernel.org>.
2cf565c5
DG
340
341Documentation
342--------------
343Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
344
345GIT
346---
347Part of the link:git.html[git] suite
348