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