Flatten tools/ directory to make build procedure simpler.
[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
2f2de9b4
JH
277link:git-convert-cache.html[git-convert-cache]::
278 Converts old-style GIT repository
279
f85a4191
JH
280link:git-cvsimport-script.html[git-cvsimport-script]::
281 Salvage your data out of another SCM people love to hate.
282
204ee6a9
DG
283link:git-merge-one-file-script.html[git-merge-one-file-script]::
284 The standard helper program to use with "git-merge-cache"
285
204ee6a9
DG
286link:git-prune-script.html[git-prune-script]::
287 Prunes all unreachable objects from the object database
288
f85a4191
JH
289link:git-relink-script.html[git-relink-script]::
290 Hardlink common objects in local repositories.
291
292link:git-sh-setup-script.html[git-sh-setup-script]::
293 Common git shell script setup code.
294
204ee6a9
DG
295link:git-tag-script.html[git-tag-script]::
296 An example script to create a tag object signed with GPG
297
204ee6a9 298
90933efb 299Interrogators:
204ee6a9 300
f85a4191
JH
301link:git-cherry.html[git-cherry]::
302 Find commits not merged upstream.
905197de
JH
303
304link:git-count-objects-script.html[git-count-objects-script]::
305 Count unpacked number of objects and their disk consumption.
306
99665af5 307link:git-diff-helper.html[git-diff-helper]::
204ee6a9
DG
308 Generates patch format output for git-diff-*
309
f85a4191
JH
310link:git-mailinfo.html[git-mailinfo]::
311 Extracts patch from a single e-mail message.
312
313link:git-mailsplit.html[git-mailsplit]::
314 git-mailsplit.
315
316link:git-patch-id.html[git-patch-id]::
317 Compute unique ID for a patch.
204ee6a9 318
83db04ff
JH
319link:git-send-email-script.html[git-send-email]::
320 Send patch e-mails out of "format-patch --mbox" output.
204ee6a9 321
760b6634
RS
322link:git-get-tar-commit-id.html[git-get-tar-commit-id]::
323 Extract commit ID from an archive created using git-tar-tree.
204ee6a9 324
7fc9d69f
JH
325Commands not yet documented
326---------------------------
327
7fc9d69f
JH
328link:git-build-rev-cache.html[git-build-rev-cache]::
329 git-build-rev-cache.
330
331link:git-checkout-script.html[git-checkout-script]::
332 git-checkout-script.
333
7fc9d69f
JH
334link:git-daemon.html[git-daemon]::
335 git-daemon.
336
337link:git-diff-script.html[git-diff-script]::
338 git-diff-script.
339
340link:git-format-patch-script.html[git-format-patch-script]::
341 git-format-patch-script.
342
7fc9d69f
JH
343link:git-request-pull-script.html[git-request-pull-script]::
344 git-request-pull-script.
345
346link:git-reset-script.html[git-reset-script]::
347 git-reset-script.
348
349link:git-rev-parse.html[git-rev-parse]::
350 git-rev-parse.
351
7fc9d69f
JH
352link:git-show-rev-cache.html[git-show-rev-cache]::
353 git-show-rev-cache.
354
355link:git-stripspace.html[git-stripspace]::
356 git-stripspace.
357
7fc9d69f
JH
358link:gitk.html[gitk]::
359 gitk.
360
361
6c84e2e0 362Identifier Terminology
2cf565c5
DG
363----------------------
364<object>::
6c84e2e0 365 Indicates the sha1 identifier for any type of object
2cf565c5
DG
366
367<blob>::
368 Indicates a blob object sha1 identifier
369
370<tree>::
371 Indicates a tree object sha1 identifier
372
373<commit>::
374 Indicates a commit object sha1 identifier
375
376<tree-ish>::
6c84e2e0
DG
377 Indicates a tree, commit or tag object sha1 identifier. A
378 command that takes a <tree-ish> argument ultimately wants to
379 operate on a <tree> object but automatically dereferences
380 <commit> and <tag> objects that point at a <tree>.
2cf565c5
DG
381
382<type>::
383 Indicates that an object type is required.
384 Currently one of: blob/tree/commit/tag
385
386<file>::
387 Indicates a filename - always relative to the root of
388 the tree structure GIT_INDEX_FILE describes.
389
c1bdacf9
DG
390Symbolic Identifiers
391--------------------
90933efb 392Any git command accepting any <object> can also use the following
6c84e2e0 393symbolic notation:
c1bdacf9
DG
394
395HEAD::
6c84e2e0
DG
396 indicates the head of the repository (ie the contents of
397 `$GIT_DIR/HEAD`)
c1bdacf9
DG
398<tag>::
399 a valid tag 'name'+
400 (ie the contents of `$GIT_DIR/refs/tags/<tag>`)
401<head>::
402 a valid head 'name'+
403 (ie the contents of `$GIT_DIR/refs/heads/<head>`)
404<snap>::
405 a valid snapshot 'name'+
406 (ie the contents of `$GIT_DIR/refs/snap/<snap>`)
407
408
409File/Directory Structure
410------------------------
c1bdacf9 411
a1d4aa74 412Please see link:repository-layout.html[repository layout] document.
c1bdacf9
DG
413
414Higher level SCMs may provide and manage additional information in the
415GIT_DIR.
416
a1d4aa74 417
2cf565c5
DG
418Terminology
419-----------
1bff6490 420Please see link:glossary.html[glossary] document.
2cf565c5
DG
421
422
423Environment Variables
424---------------------
425Various git commands use the following environment variables:
426
c1bdacf9
DG
427The git Repository
428~~~~~~~~~~~~~~~~~~
429These environment variables apply to 'all' core git commands. Nb: it
430is worth noting that they may be used/overridden by SCMS sitting above
431git so take care if using Cogito etc
432
433'GIT_INDEX_FILE'::
434 This environment allows the specification of an alternate
435 cache/index file. If not specified, the default of
436 `$GIT_DIR/index` is used.
437
438'GIT_OBJECT_DIRECTORY'::
439 If the object storage directory is specified via this
440 environment variable then the sha1 directories are created
441 underneath - otherwise the default `$GIT_DIR/objects`
442 directory is used.
443
444'GIT_ALTERNATE_OBJECT_DIRECTORIES'::
445 Due to the immutable nature of git objects, old objects can be
446 archived into shared, read-only directories. This variable
90933efb 447 specifies a ":" separated list of git object directories which
c1bdacf9
DG
448 can be used to search for git objects. New objects will not be
449 written to these directories.
450
451'GIT_DIR'::
452 If the 'GIT_DIR' environment variable is set then it specifies
453 a path to use instead of `./.git` for the base of the
454 repository.
455
456git Commits
457~~~~~~~~~~~
458'GIT_AUTHOR_NAME'::
459'GIT_AUTHOR_EMAIL'::
460'GIT_AUTHOR_DATE'::
461'GIT_COMMITTER_NAME'::
462'GIT_COMMITTER_EMAIL'::
463 see link:git-commit-tree.html[git-commit-tree]
464
465git Diffs
466~~~~~~~~~
d81ed1b5
JH
467'GIT_DIFF_OPTS'::
468'GIT_EXTERNAL_DIFF'::
c1bdacf9
DG
469 see the "generating patches" section in :
470 link:git-diff-cache.html[git-diff-cache];
471 link:git-diff-files.html[git-diff-files];
472 link:git-diff-tree.html[git-diff-tree]
2cf565c5 473
8db9307c
JH
474Discussion[[Discussion]]
475------------------------
6c84e2e0
DG
476include::../README[]
477
2cf565c5
DG
478Author
479------
6c84e2e0 480Written by Linus Torvalds <torvalds@osdl.org> and the git-list <git@vger.kernel.org>.
2cf565c5
DG
481
482Documentation
483--------------
484Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
485
486GIT
487---
488Part of the link:git.html[git] suite
489