GIT 0.99.6
[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
452ce291
JH
212link:git-checkout-script.html[git-checkout-script]::
213 Checkout and switch to a branch.
214
f85a4191
JH
215link:git-cherry-pick-script.html[git-cherry-pick-script]::
216 Cherry-pick the effect of an existing commit.
3f971fc4 217
f85a4191
JH
218link:git-clone-script.html[git-clone-script]::
219 Clones a repository into a new directory.
3f971fc4 220
f85a4191
JH
221link:git-commit-script.html[git-commit-script]::
222 Record changes to the repository.
3f971fc4 223
62033318
JH
224link:git-fetch-script.html[git-fetch-script]::
225 Download from a remote repository via various protocols.
226
f85a4191
JH
227link:git-log-script.html[git-log-script]::
228 Shows commit logs.
62033318 229
f85a4191
JH
230link:git-ls-remote-script.html[git-ls-remote-script]::
231 Shows references in a remote or local repository.
ab9b3138
JH
232
233link:git-octopus-script.html[git-octopus-script]::
234 Merge more than two commits.
235
f85a4191
JH
236link:git-pull-script.html[git-pull-script]::
237 Fetch from and merge with a remote repository.
238
ab9b3138
JH
239link:git-push-script.html[git-push-script]::
240 Update remote refs along with associated objects.
241
f85a4191
JH
242link:git-rebase-script.html[git-rebase-script]::
243 Rebase local commits to new upstream head.
62033318 244
f85a4191
JH
245link:git-rename-script.html[git-rename]::
246 Rename files and directories.
62033318 247
e31bb3bb
JH
248link:git-repack-script.html[git-repack-script]::
249 Pack unpacked objects in a repository.
250
452ce291
JH
251link:git-reset-script.html[git-reset-script]::
252 Reset current HEAD to the specified state.
253
f85a4191
JH
254link:git-resolve-script.html[git-resolve-script]::
255 Merge two commits.
83db04ff 256
f85a4191
JH
257link:git-revert-script.html[git-revert-script]::
258 Revert an existing commit.
259
260link:git-shortlog.html[git-shortlog]::
261 Summarizes 'git log' output.
262
263link:git-show-branch.html[git-show-branch]::
264 Show branches and their commits.
265
266link:git-status-script.html[git-status-script]::
267 Shows the working tree status.
83db04ff 268
905197de
JH
269link:git-verify-tag-script.html[git-verify-tag-script]::
270 Check the GPG signature of tag.
271
f85a4191
JH
272link:git-whatchanged.html[git-whatchanged]::
273 Shows commit logs and differences they introduce.
274
e31bb3bb 275
90933efb
YS
276Ancillary Commands
277------------------
2f2de9b4
JH
278Manipulators:
279
f85a4191
JH
280link:git-applypatch.html[git-applypatch]::
281 Apply one patch extracted from an e-mail.
905197de 282
5077fa9c
JH
283link:git-archimport-script.html[git-archimport-script]::
284 Import an arch repository into git.
285
2f2de9b4
JH
286link:git-convert-cache.html[git-convert-cache]::
287 Converts old-style GIT repository
288
f85a4191
JH
289link:git-cvsimport-script.html[git-cvsimport-script]::
290 Salvage your data out of another SCM people love to hate.
291
204ee6a9
DG
292link:git-merge-one-file-script.html[git-merge-one-file-script]::
293 The standard helper program to use with "git-merge-cache"
294
204ee6a9
DG
295link:git-prune-script.html[git-prune-script]::
296 Prunes all unreachable objects from the object database
297
f85a4191
JH
298link:git-relink-script.html[git-relink-script]::
299 Hardlink common objects in local repositories.
300
301link:git-sh-setup-script.html[git-sh-setup-script]::
302 Common git shell script setup code.
303
204ee6a9
DG
304link:git-tag-script.html[git-tag-script]::
305 An example script to create a tag object signed with GPG
306
204ee6a9 307
90933efb 308Interrogators:
204ee6a9 309
452ce291
JH
310link:git-build-rev-cache.html[git-build-rev-cache]::
311 Create or update a rev-cache file.
312
f85a4191
JH
313link:git-cherry.html[git-cherry]::
314 Find commits not merged upstream.
905197de
JH
315
316link:git-count-objects-script.html[git-count-objects-script]::
317 Count unpacked number of objects and their disk consumption.
318
5077fa9c
JH
319link:git-daemon.html[git-daemon]::
320 A really simple server for GIT repositories.
321
99665af5 322link:git-diff-helper.html[git-diff-helper]::
204ee6a9
DG
323 Generates patch format output for git-diff-*
324
5077fa9c
JH
325link:git-get-tar-commit-id.html[git-get-tar-commit-id]::
326 Extract commit ID from an archive created using git-tar-tree.
327
f85a4191
JH
328link:git-mailinfo.html[git-mailinfo]::
329 Extracts patch from a single e-mail message.
330
331link:git-mailsplit.html[git-mailsplit]::
332 git-mailsplit.
333
334link:git-patch-id.html[git-patch-id]::
335 Compute unique ID for a patch.
204ee6a9 336
5077fa9c
JH
337link:git-parse-remote-script.html[git-parse-remote-script]::
338 Routines to help parsing $GIT_DIR/remotes/
339
340link:git-request-pull-script.html[git-request-pull-script]::
341 git-request-pull-script.
342
343link:git-rev-parse.html[git-rev-parse]::
344 Pick out and massage parameters.
345
83db04ff
JH
346link:git-send-email-script.html[git-send-email]::
347 Send patch e-mails out of "format-patch --mbox" output.
204ee6a9 348
452ce291
JH
349link:git-show-rev-cache.html[git-show-rev-cache]::
350 Show the contents of a rev-cache file.
351
7fc9d69f
JH
352Commands not yet documented
353---------------------------
354
7fc9d69f
JH
355link:git-diff-script.html[git-diff-script]::
356 git-diff-script.
357
358link:git-format-patch-script.html[git-format-patch-script]::
359 git-format-patch-script.
360
7fc9d69f
JH
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