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