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