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