[PATCH] Docs for git-build-rev-cache.
[git/git.git] / Documentation / git.txt
CommitLineData
7984eabe 1git(7)
2cf565c5 2======
905197de 3v0.99.5, Aug 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
0d6a873c
JH
19Before reading this cover to cover, you may want to take a look
20at the link:tutorial.html[tutorial] document.
21
8db9307c 22The <<Discussion>> section below contains much useful definition and
6c84e2e0
DG
23clarification info - read that first. And of the commands, I suggest
24reading link:git-update-cache.html[git-update-cache] and
25link:git-read-tree.html[git-read-tree] first - I wish I had!
2cf565c5 26
8db9307c
JH
27If you are migrating from CVS, link:cvs-migration.html[cvs migration]
28document may be helpful after you finish the tutorial.
29
e6fc2346
JH
30After you get the general feel from the tutorial and this
31overview page, you may want to take a look at the
32link:howto-index.html[howto] documents.
33
34
2cf565c5
DG
35David Greaves <david@dgreaves.com>
3608/05/05
37
38Updated by Junio C Hamano <junkio@cox.net> on 2005-05-05 to
39reflect recent changes.
40
41Commands Overview
42-----------------
43The git commands can helpfully be split into those that manipulate
2f2de9b4
JH
44the repository, the cache and the working fileset, those that
45interrogate and compare them, and those that moves objects and
46references between repositories.
2cf565c5 47
62033318
JH
48In addition, git itself comes with a spartan set of porcelain
49commands. They are usable but are not meant to compete with real
50Porcelains.
51
90933efb 52There are also some ancillary programs that can be viewed as useful
204ee6a9
DG
53aids for using the core commands but which are unlikely to be used by
54SCMs layered over git.
55
2cf565c5
DG
56Manipulation commands
57~~~~~~~~~~~~~~~~~~~~~
f85a4191
JH
58link:git-apply.html[git-apply]::
59 Reads a "diff -up1" or git generated patch file and
60 applies it to the working tree.
61
2cf565c5
DG
62link:git-checkout-cache.html[git-checkout-cache]::
63 Copy files from the cache to the working directory
64
65link:git-commit-tree.html[git-commit-tree]::
66 Creates a new commit object
67
f85a4191
JH
68link:git-hash-object.html[git-hash-object]::
69 Computes the object ID from a file.
70
2cf565c5
DG
71link:git-init-db.html[git-init-db]::
72 Creates an empty git object database
73
f85a4191
JH
74link:git-merge-cache.html[git-merge-cache]::
75 Runs a merge for files needing merging
2cf565c5 76
2cf565c5
DG
77link:git-mktag.html[git-mktag]::
78 Creates a tag object
79
f85a4191
JH
80link:git-pack-objects.html[git-pack-objects]::
81 Creates a packed archive of objects.
82
83link:git-prune-packed.html[git-prune-packed]::
84 Remove extra objects that are already in pack files.
85
2cf565c5
DG
86link:git-read-tree.html[git-read-tree]::
87 Reads tree information into the directory cache
88
f85a4191
JH
89link:git-unpack-objects.html[git-unpack-objects]::
90 Unpacks objects out of a packed archive.
91
2cf565c5
DG
92link:git-update-cache.html[git-update-cache]::
93 Modifies the index or directory cache
94
2cf565c5
DG
95link:git-write-tree.html[git-write-tree]::
96 Creates a tree from the current cache
97
e31bb3bb 98
2cf565c5
DG
99Interrogation commands
100~~~~~~~~~~~~~~~~~~~~~~
f85a4191 101
2cf565c5
DG
102link:git-cat-file.html[git-cat-file]::
103 Provide content or type information for repository objects
104
2cf565c5
DG
105link:git-diff-cache.html[git-diff-cache]::
106 Compares content and mode of blobs between the cache and repository
107
108link:git-diff-files.html[git-diff-files]::
109 Compares files in the working tree and the cache
110
83db04ff
JH
111link:git-diff-stages.html[git-diff-stages]::
112 Compares two "merge stages" in the index file.
113
f85a4191
JH
114link:git-diff-tree.html[git-diff-tree]::
115 Compares the content and mode of blobs found via two tree objects
116
2cf565c5
DG
117link:git-export.html[git-export]::
118 Exports each commit and a diff against each of its parents
119
120link:git-fsck-cache.html[git-fsck-cache]::
121 Verifies the connectivity and validity of the objects in the database
122
123link:git-ls-files.html[git-ls-files]::
124 Information about files in the cache/working directory
125
126link:git-ls-tree.html[git-ls-tree]::
127 Displays a tree object in human readable form
128
f85a4191
JH
129link:git-merge-base.html[git-merge-base]::
130 Finds as good a common ancestor as possible for a merge
2cf565c5
DG
131
132link:git-rev-list.html[git-rev-list]::
133 Lists commit objects in reverse chronological order
134
135link:git-rev-tree.html[git-rev-tree]::
136 Provides the revision tree for one or more commits
137
f85a4191
JH
138link:git-show-index.html[git-show-index]::
139 Displays contents of a pack idx file.
140
2cf565c5
DG
141link:git-tar-tree.html[git-tar-tree]::
142 Creates a tar archive of the files in the named tree
143
144link:git-unpack-file.html[git-unpack-file]::
145 Creates a temporary file with a blob's contents
146
aed022ab
EB
147link:git-var.html[git-var]::
148 Displays a git logical variable
149
f9253394
JH
150link:git-verify-pack.html[git-verify-pack]::
151 Validates packed GIT archive files
152
2cf565c5
DG
153The interrogate commands may create files - and you can force them to
154touch the working file set - but in general they don't
155
156
0c04094b
JH
157Synching repositories
158~~~~~~~~~~~~~~~~~~~~~
159
6ec311da
JH
160link:git-clone-pack.html[git-clone-pack]::
161 Clones a repository into the current repository (engine
162 for ssh and local transport)
163
f85a4191
JH
164link:git-fetch-pack.html[git-fetch-pack]::
165 Updates from a remote repository.
166
204ee6a9
DG
167link:git-http-pull.html[git-http-pull]::
168 Downloads a remote GIT repository via HTTP
169
170link:git-local-pull.html[git-local-pull]::
171 Duplicates another GIT repository on a local system
172
f85a4191
JH
173link:git-peek-remote.html[git-peek-remote]::
174 Lists references on a remote repository using upload-pack protocol.
2f2de9b4
JH
175
176link:git-receive-pack.html[git-receive-pack]::
177 Invoked by 'git-send-pack' to receive what is pushed to it.
178
f85a4191
JH
179link:git-send-pack.html[git-send-pack]::
180 Pushes to a remote repository, intelligently.
2f2de9b4 181
f85a4191
JH
182link:git-ssh-pull.html[git-ssh-pull]::
183 Pulls from a remote repository over ssh connection
508e67ab 184
f85a4191
JH
185link:git-ssh-push.html[git-ssh-push]::
186 Helper "server-side" program used by git-ssh-pull
2f2de9b4 187
61e3ef36
JH
188link:git-update-server-info.html[git-update-server-info]::
189 Updates auxiliary information on a dumb server to help
190 clients discover references and packs on it.
191
f85a4191
JH
192link:git-upload-pack.html[git-upload-pack]::
193 Invoked by 'git-clone-pack' and 'git-fetch-pack' to push
194 what are asked for.
195
2f2de9b4 196
3f971fc4
JH
197Porcelain-ish Commands
198----------------------
905197de
JH
199
200link:git-add-script.html[git-add-script]::
201 Add paths to the index file.
202
f85a4191
JH
203link:git-applymbox.html[git-applymbox]::
204 Apply patches from a mailbox.
205
206link:git-bisect-script.html[git-bisect-script]::
207 Find the change that introduced a bug.
208
905197de
JH
209link:git-branch-script.html[git-branch-script]::
210 Create and Show branches.
211
f85a4191
JH
212link:git-cherry-pick-script.html[git-cherry-pick-script]::
213 Cherry-pick the effect of an existing commit.
3f971fc4 214
f85a4191
JH
215link:git-clone-script.html[git-clone-script]::
216 Clones a repository into a new directory.
3f971fc4 217
f85a4191
JH
218link:git-commit-script.html[git-commit-script]::
219 Record changes to the repository.
3f971fc4 220
62033318
JH
221link:git-fetch-script.html[git-fetch-script]::
222 Download from a remote repository via various protocols.
223
f85a4191
JH
224link:git-log-script.html[git-log-script]::
225 Shows commit logs.
62033318 226
f85a4191
JH
227link:git-ls-remote-script.html[git-ls-remote-script]::
228 Shows references in a remote or local repository.
ab9b3138
JH
229
230link:git-octopus-script.html[git-octopus-script]::
231 Merge more than two commits.
232
f85a4191
JH
233link:git-pull-script.html[git-pull-script]::
234 Fetch from and merge with a remote repository.
235
ab9b3138
JH
236link:git-push-script.html[git-push-script]::
237 Update remote refs along with associated objects.
238
f85a4191
JH
239link:git-rebase-script.html[git-rebase-script]::
240 Rebase local commits to new upstream head.
62033318 241
f85a4191
JH
242link:git-rename-script.html[git-rename]::
243 Rename files and directories.
62033318 244
e31bb3bb
JH
245link:git-repack-script.html[git-repack-script]::
246 Pack unpacked objects in a repository.
247
f85a4191
JH
248link:git-resolve-script.html[git-resolve-script]::
249 Merge two commits.
83db04ff 250
f85a4191
JH
251link:git-revert-script.html[git-revert-script]::
252 Revert an existing commit.
253
254link:git-shortlog.html[git-shortlog]::
255 Summarizes 'git log' output.
256
257link:git-show-branch.html[git-show-branch]::
258 Show branches and their commits.
259
260link:git-status-script.html[git-status-script]::
261 Shows the working tree status.
83db04ff 262
905197de
JH
263link:git-verify-tag-script.html[git-verify-tag-script]::
264 Check the GPG signature of tag.
265
f85a4191
JH
266link:git-whatchanged.html[git-whatchanged]::
267 Shows commit logs and differences they introduce.
268
e31bb3bb 269
90933efb
YS
270Ancillary Commands
271------------------
2f2de9b4
JH
272Manipulators:
273
f85a4191
JH
274link:git-applypatch.html[git-applypatch]::
275 Apply one patch extracted from an e-mail.
905197de 276
5077fa9c
JH
277link:git-archimport-script.html[git-archimport-script]::
278 Import an arch repository into git.
279
2f2de9b4
JH
280link:git-convert-cache.html[git-convert-cache]::
281 Converts old-style GIT repository
282
f85a4191
JH
283link:git-cvsimport-script.html[git-cvsimport-script]::
284 Salvage your data out of another SCM people love to hate.
285
204ee6a9
DG
286link:git-merge-one-file-script.html[git-merge-one-file-script]::
287 The standard helper program to use with "git-merge-cache"
288
204ee6a9
DG
289link:git-prune-script.html[git-prune-script]::
290 Prunes all unreachable objects from the object database
291
f85a4191
JH
292link:git-relink-script.html[git-relink-script]::
293 Hardlink common objects in local repositories.
294
295link:git-sh-setup-script.html[git-sh-setup-script]::
296 Common git shell script setup code.
297
204ee6a9
DG
298link:git-tag-script.html[git-tag-script]::
299 An example script to create a tag object signed with GPG
300
204ee6a9 301
90933efb 302Interrogators:
204ee6a9 303
f85a4191
JH
304link:git-cherry.html[git-cherry]::
305 Find commits not merged upstream.
905197de
JH
306
307link:git-count-objects-script.html[git-count-objects-script]::
308 Count unpacked number of objects and their disk consumption.
309
5077fa9c
JH
310link:git-daemon.html[git-daemon]::
311 A really simple server for GIT repositories.
312
99665af5 313link:git-diff-helper.html[git-diff-helper]::
204ee6a9
DG
314 Generates patch format output for git-diff-*
315
5077fa9c
JH
316link:git-get-tar-commit-id.html[git-get-tar-commit-id]::
317 Extract commit ID from an archive created using git-tar-tree.
318
f85a4191
JH
319link:git-mailinfo.html[git-mailinfo]::
320 Extracts patch from a single e-mail message.
321
322link:git-mailsplit.html[git-mailsplit]::
323 git-mailsplit.
324
325link:git-patch-id.html[git-patch-id]::
326 Compute unique ID for a patch.
204ee6a9 327
5077fa9c
JH
328link:git-parse-remote-script.html[git-parse-remote-script]::
329 Routines to help parsing $GIT_DIR/remotes/
330
331link:git-request-pull-script.html[git-request-pull-script]::
332 git-request-pull-script.
333
334link:git-rev-parse.html[git-rev-parse]::
335 Pick out and massage parameters.
336
83db04ff
JH
337link:git-send-email-script.html[git-send-email]::
338 Send patch e-mails out of "format-patch --mbox" output.
204ee6a9 339
7fc9d69f
JH
340Commands not yet documented
341---------------------------
342
7fc9d69f
JH
343link:git-build-rev-cache.html[git-build-rev-cache]::
344 git-build-rev-cache.
345
346link:git-checkout-script.html[git-checkout-script]::
347 git-checkout-script.
348
7fc9d69f
JH
349link:git-diff-script.html[git-diff-script]::
350 git-diff-script.
351
352link:git-format-patch-script.html[git-format-patch-script]::
353 git-format-patch-script.
354
7fc9d69f
JH
355link:git-reset-script.html[git-reset-script]::
356 git-reset-script.
357
7fc9d69f
JH
358link:git-show-rev-cache.html[git-show-rev-cache]::
359 git-show-rev-cache.
360
361link:git-stripspace.html[git-stripspace]::
362 git-stripspace.
363
7fc9d69f
JH
364link:gitk.html[gitk]::
365 gitk.
366
367
6c84e2e0 368Identifier Terminology
2cf565c5
DG
369----------------------
370<object>::
6c84e2e0 371 Indicates the sha1 identifier for any type of object
2cf565c5
DG
372
373<blob>::
374 Indicates a blob object sha1 identifier
375
376<tree>::
377 Indicates a tree object sha1 identifier
378
379<commit>::
380 Indicates a commit object sha1 identifier
381
382<tree-ish>::
6c84e2e0
DG
383 Indicates a tree, commit or tag object sha1 identifier. A
384 command that takes a <tree-ish> argument ultimately wants to
385 operate on a <tree> object but automatically dereferences
386 <commit> and <tag> objects that point at a <tree>.
2cf565c5
DG
387
388<type>::
389 Indicates that an object type is required.
390 Currently one of: blob/tree/commit/tag
391
392<file>::
393 Indicates a filename - always relative to the root of
394 the tree structure GIT_INDEX_FILE describes.
395
c1bdacf9
DG
396Symbolic Identifiers
397--------------------
90933efb 398Any git command accepting any <object> can also use the following
6c84e2e0 399symbolic notation:
c1bdacf9
DG
400
401HEAD::
6c84e2e0
DG
402 indicates the head of the repository (ie the contents of
403 `$GIT_DIR/HEAD`)
c1bdacf9
DG
404<tag>::
405 a valid tag 'name'+
406 (ie the contents of `$GIT_DIR/refs/tags/<tag>`)
407<head>::
408 a valid head 'name'+
409 (ie the contents of `$GIT_DIR/refs/heads/<head>`)
410<snap>::
411 a valid snapshot 'name'+
412 (ie the contents of `$GIT_DIR/refs/snap/<snap>`)
413
414
415File/Directory Structure
416------------------------
c1bdacf9 417
a1d4aa74 418Please see link:repository-layout.html[repository layout] document.
c1bdacf9
DG
419
420Higher level SCMs may provide and manage additional information in the
421GIT_DIR.
422
a1d4aa74 423
2cf565c5
DG
424Terminology
425-----------
1bff6490 426Please see link:glossary.html[glossary] document.
2cf565c5
DG
427
428
429Environment Variables
430---------------------
431Various git commands use the following environment variables:
432
c1bdacf9
DG
433The git Repository
434~~~~~~~~~~~~~~~~~~
435These environment variables apply to 'all' core git commands. Nb: it
436is worth noting that they may be used/overridden by SCMS sitting above
437git so take care if using Cogito etc
438
439'GIT_INDEX_FILE'::
440 This environment allows the specification of an alternate
441 cache/index file. If not specified, the default of
442 `$GIT_DIR/index` is used.
443
444'GIT_OBJECT_DIRECTORY'::
445 If the object storage directory is specified via this
446 environment variable then the sha1 directories are created
447 underneath - otherwise the default `$GIT_DIR/objects`
448 directory is used.
449
450'GIT_ALTERNATE_OBJECT_DIRECTORIES'::
451 Due to the immutable nature of git objects, old objects can be
452 archived into shared, read-only directories. This variable
90933efb 453 specifies a ":" separated list of git object directories which
c1bdacf9
DG
454 can be used to search for git objects. New objects will not be
455 written to these directories.
456
457'GIT_DIR'::
458 If the 'GIT_DIR' environment variable is set then it specifies
459 a path to use instead of `./.git` for the base of the
460 repository.
461
462git Commits
463~~~~~~~~~~~
464'GIT_AUTHOR_NAME'::
465'GIT_AUTHOR_EMAIL'::
466'GIT_AUTHOR_DATE'::
467'GIT_COMMITTER_NAME'::
468'GIT_COMMITTER_EMAIL'::
469 see link:git-commit-tree.html[git-commit-tree]
470
471git Diffs
472~~~~~~~~~
d81ed1b5
JH
473'GIT_DIFF_OPTS'::
474'GIT_EXTERNAL_DIFF'::
c1bdacf9
DG
475 see the "generating patches" section in :
476 link:git-diff-cache.html[git-diff-cache];
477 link:git-diff-files.html[git-diff-files];
478 link:git-diff-tree.html[git-diff-tree]
2cf565c5 479
8db9307c
JH
480Discussion[[Discussion]]
481------------------------
6c84e2e0
DG
482include::../README[]
483
2cf565c5
DG
484Author
485------
6c84e2e0 486Written by Linus Torvalds <torvalds@osdl.org> and the git-list <git@vger.kernel.org>.
2cf565c5
DG
487
488Documentation
489--------------
490Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
491
492GIT
493---
494Part of the link:git.html[git] suite
495