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