Merge branch 'jc/combine' into next
[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--------
cb22bc44 11'git' [--version] [--exec-path[=GIT_EXEC_PATH]] [--help] COMMAND [ARGS]
2cf565c5
DG
12
13DESCRIPTION
14-----------
23091e95
BF
15Git is a fast, scalable, distributed revision control system with an
16unusually rich command set that provides both high-level operations
17and full access to internals.
18
19See this link:tutorial.html[tutorial] to get started, then see
20link:everyday.html[Everyday Git] for a useful minimum set of commands, and
21"man git-commandname" for documentation of each command. CVS users may
22also want to read link:cvs-migration.html[CVS migration].
cb22bc44
AE
23
24OPTIONS
25-------
26--version::
a87cd02c 27 Prints the git suite version that the 'git' program came from.
cb22bc44
AE
28
29--help::
a87cd02c
FK
30 Prints the synopsis and a list of the most commonly used
31 commands. If a git command is named this option will bring up
32 the man-page for that command. If the option '--all' or '-a' is
33 given then all available commands are printed.
cb22bc44
AE
34
35--exec-path::
a87cd02c 36 Path to wherever your core git programs are installed.
cb22bc44
AE
37 This can also be controlled by setting the GIT_EXEC_PATH
38 environment variable. If no path is given 'git' will print
39 the current setting and then exit.
40
9755afbd 41
23091e95
BF
42FURTHER DOCUMENTATION
43---------------------
9755afbd 44
23091e95
BF
45See the references above to get started using git. The following is
46probably more detail than necessary for a first-time user.
8db9307c 47
23091e95
BF
48The <<Discussion,Discussion>> section below and the
49link:core-tutorial.html[Core tutorial] both provide introductions to the
50underlying git architecture.
e6fc2346 51
23091e95
BF
52See also the link:howto-index.html[howto] documents for some useful
53examples.
9755afbd 54
23091e95
BF
55GIT COMMANDS
56------------
9755afbd 57
23091e95
BF
58We divide git into high level ("porcelain") commands and low level
59("plumbing") commands.
8b15e2fb 60
23091e95
BF
61Low-level commands (plumbing)
62-----------------------------
e6fc2346 63
23091e95
BF
64Although git includes its
65own porcelain layer, its low-level commands are sufficient to support
66development of alternative porcelains. Developers of such porcelains
67might start by reading about gitlink:git-update-index[1] and
68gitlink:git-read-tree[1].
2cf565c5 69
23091e95
BF
70We divide the low-level commands into commands that manipulate objects (in
71the repository, index, and working tree), commands that interrogate and
72compare objects, and commands that move objects and references between
73repositories.
204ee6a9 74
2cf565c5
DG
75Manipulation commands
76~~~~~~~~~~~~~~~~~~~~~
a7154e91 77gitlink:git-apply[1]::
f85a4191
JH
78 Reads a "diff -up1" or git generated patch file and
79 applies it to the working tree.
80
a7154e91 81gitlink:git-checkout-index[1]::
2fa090b6 82 Copy files from the index to the working tree.
2cf565c5 83
a7154e91 84gitlink:git-commit-tree[1]::
2fa090b6 85 Creates a new commit object.
2cf565c5 86
a7154e91 87gitlink:git-hash-object[1]::
f85a4191
JH
88 Computes the object ID from a file.
89
a52e4ef8 90gitlink:git-index-pack[1]::
2fa090b6 91 Build pack idx file for an existing packed archive.
9cf6d335 92
a7154e91 93gitlink:git-init-db[1]::
2fa090b6
JH
94 Creates an empty git object database, or reinitialize an
95 existing one.
2cf565c5 96
a7154e91 97gitlink:git-merge-index[1]::
2fa090b6 98 Runs a merge for files needing merging.
2cf565c5 99
a7154e91 100gitlink:git-mktag[1]::
2fa090b6 101 Creates a tag object.
2cf565c5 102
a7154e91 103gitlink:git-pack-objects[1]::
f85a4191
JH
104 Creates a packed archive of objects.
105
a7154e91 106gitlink:git-prune-packed[1]::
f85a4191
JH
107 Remove extra objects that are already in pack files.
108
a7154e91 109gitlink:git-read-tree[1]::
2fa090b6 110 Reads tree information into the index.
2cf565c5 111
ee72aeaf
JS
112gitlink:git-repo-config[1]::
113 Get and set options in .git/config.
114
a7154e91 115gitlink:git-unpack-objects[1]::
f85a4191
JH
116 Unpacks objects out of a packed archive.
117
a7154e91 118gitlink:git-update-index[1]::
2fa090b6 119 Registers files in the working tree to the index.
2cf565c5 120
a7154e91 121gitlink:git-write-tree[1]::
2fa090b6 122 Creates a tree from the index.
2cf565c5 123
e31bb3bb 124
2cf565c5
DG
125Interrogation commands
126~~~~~~~~~~~~~~~~~~~~~~
f85a4191 127
a7154e91 128gitlink:git-cat-file[1]::
2fa090b6 129 Provide content or type/size information for repository objects.
2cf565c5 130
c06818e2
JH
131gitlink:git-describe[1]::
132 Show the most recent tag that is reachable from a commit.
133
a7154e91 134gitlink:git-diff-index[1]::
2fa090b6 135 Compares content and mode of blobs between the index and repository.
2cf565c5 136
a7154e91 137gitlink:git-diff-files[1]::
2fa090b6 138 Compares files in the working tree and the index.
2cf565c5 139
a7154e91 140gitlink:git-diff-stages[1]::
2fa090b6 141 Compares two "merge stages" in the index.
83db04ff 142
a7154e91 143gitlink:git-diff-tree[1]::
2fa090b6 144 Compares the content and mode of blobs found via two tree objects.
f85a4191 145
a7154e91 146gitlink:git-fsck-objects[1]::
2fa090b6 147 Verifies the connectivity and validity of the objects in the database.
2cf565c5 148
a7154e91 149gitlink:git-ls-files[1]::
2fa090b6 150 Information about files in the index and the working tree.
2cf565c5 151
a7154e91 152gitlink:git-ls-tree[1]::
2fa090b6 153 Displays a tree object in human readable form.
2cf565c5 154
a7154e91 155gitlink:git-merge-base[1]::
2fa090b6 156 Finds as good common ancestors as possible for a merge.
2cf565c5 157
a60d2d8f 158gitlink:git-name-rev[1]::
2fa090b6 159 Find symbolic names for given revs.
a60d2d8f 160
76cead39
JH
161gitlink:git-pack-redundant[1]::
162 Find redundant pack files.
163
a7154e91 164gitlink:git-rev-list[1]::
2fa090b6 165 Lists commit objects in reverse chronological order.
2cf565c5 166
a7154e91 167gitlink:git-show-index[1]::
f85a4191
JH
168 Displays contents of a pack idx file.
169
a7154e91 170gitlink:git-tar-tree[1]::
2fa090b6 171 Creates a tar archive of the files in the named tree object.
2cf565c5 172
a7154e91 173gitlink:git-unpack-file[1]::
2fa090b6 174 Creates a temporary file with a blob's contents.
2cf565c5 175
a7154e91 176gitlink:git-var[1]::
2fa090b6 177 Displays a git logical variable.
aed022ab 178
a7154e91 179gitlink:git-verify-pack[1]::
2fa090b6 180 Validates packed git archive files.
f9253394 181
2fa090b6
JH
182In general, the interrogate commands do not touch the files in
183the working tree.
2cf565c5
DG
184
185
0c04094b
JH
186Synching repositories
187~~~~~~~~~~~~~~~~~~~~~
188
a7154e91 189gitlink:git-clone-pack[1]::
6ec311da 190 Clones a repository into the current repository (engine
2fa090b6 191 for ssh and local transport).
6ec311da 192
a7154e91 193gitlink:git-fetch-pack[1]::
2fa090b6
JH
194 Updates from a remote repository (engine for ssh and
195 local transport).
f85a4191 196
a7154e91 197gitlink:git-http-fetch[1]::
2fa090b6
JH
198 Downloads a remote git repository via HTTP by walking
199 commit chain.
204ee6a9 200
a7154e91 201gitlink:git-local-fetch[1]::
2fa090b6
JH
202 Duplicates another git repository on a local system by
203 walking commit chain.
204ee6a9 204
a7154e91 205gitlink:git-peek-remote[1]::
2fa090b6
JH
206 Lists references on a remote repository using
207 upload-pack protocol (engine for ssh and local
208 transport).
2f2de9b4 209
a7154e91 210gitlink:git-receive-pack[1]::
2f2de9b4
JH
211 Invoked by 'git-send-pack' to receive what is pushed to it.
212
a7154e91 213gitlink:git-send-pack[1]::
f85a4191 214 Pushes to a remote repository, intelligently.
2f2de9b4 215
76cead39
JH
216gitlink:git-http-push[1]::
217 Push missing objects using HTTP/DAV.
218
d43367af
PB
219gitlink:git-shell[1]::
220 Restricted shell for GIT-only SSH access.
221
a7154e91 222gitlink:git-ssh-fetch[1]::
2fa090b6
JH
223 Pulls from a remote repository over ssh connection by
224 walking commit chain.
508e67ab 225
a7154e91 226gitlink:git-ssh-upload[1]::
2fa090b6 227 Helper "server-side" program used by git-ssh-fetch.
2f2de9b4 228
a7154e91 229gitlink:git-update-server-info[1]::
61e3ef36
JH
230 Updates auxiliary information on a dumb server to help
231 clients discover references and packs on it.
232
a7154e91 233gitlink:git-upload-pack[1]::
f85a4191
JH
234 Invoked by 'git-clone-pack' and 'git-fetch-pack' to push
235 what are asked for.
236
2f2de9b4 237
23091e95
BF
238High-level commands (porcelain)
239-------------------------------
240
241We separate the porcelain commands into the main commands and some
242ancillary user utilities.
243
244Main porcelain commands
245~~~~~~~~~~~~~~~~~~~~~~~
905197de 246
a7154e91 247gitlink:git-add[1]::
2fa090b6 248 Add paths to the index.
905197de 249
8548ea8d
PB
250gitlink:git-am[1]::
251 Apply patches from a mailbox, but cooler.
252
a7154e91 253gitlink:git-applymbox[1]::
2fa090b6 254 Apply patches from a mailbox, original version by Linus.
f85a4191 255
a7154e91 256gitlink:git-bisect[1]::
2fa090b6 257 Find the change that introduced a bug by binary search.
f85a4191 258
a7154e91 259gitlink:git-branch[1]::
905197de
JH
260 Create and Show branches.
261
a7154e91 262gitlink:git-checkout[1]::
452ce291
JH
263 Checkout and switch to a branch.
264
a7154e91 265gitlink:git-cherry-pick[1]::
f85a4191 266 Cherry-pick the effect of an existing commit.
3f971fc4 267
a7154e91 268gitlink:git-clone[1]::
f85a4191 269 Clones a repository into a new directory.
3f971fc4 270
a7154e91 271gitlink:git-commit[1]::
f85a4191 272 Record changes to the repository.
3f971fc4 273
a7154e91 274gitlink:git-diff[1]::
2aba319a 275 Show changes between commits, commit and working tree, etc.
35ef3a4c 276
a7154e91 277gitlink:git-fetch[1]::
62033318
JH
278 Download from a remote repository via various protocols.
279
a7154e91 280gitlink:git-format-patch[1]::
2aba319a 281 Prepare patches for e-mail submission.
35ef3a4c 282
a7154e91 283gitlink:git-grep[1]::
2fa090b6 284 Print lines matching a pattern.
2aba319a 285
a7154e91 286gitlink:git-log[1]::
f85a4191 287 Shows commit logs.
62033318 288
a7154e91 289gitlink:git-ls-remote[1]::
f85a4191 290 Shows references in a remote or local repository.
ab9b3138 291
a7154e91 292gitlink:git-merge[1]::
0f69be53
JH
293 Grand unified merge driver.
294
8548ea8d
PB
295gitlink:git-mv[1]::
296 Move or rename a file, a directory, or a symlink.
297
a7154e91 298gitlink:git-pull[1]::
f85a4191
JH
299 Fetch from and merge with a remote repository.
300
a7154e91 301gitlink:git-push[1]::
ab9b3138
JH
302 Update remote refs along with associated objects.
303
a7154e91 304gitlink:git-rebase[1]::
2fa090b6 305 Rebase local commits to the updated upstream head.
62033318 306
a7154e91 307gitlink:git-repack[1]::
e31bb3bb
JH
308 Pack unpacked objects in a repository.
309
8389b52b
JH
310gitlink:git-rerere[1]::
311 Reuse recorded resolution of conflicted merges.
312
a7154e91 313gitlink:git-reset[1]::
452ce291
JH
314 Reset current HEAD to the specified state.
315
a7154e91 316gitlink:git-resolve[1]::
f85a4191 317 Merge two commits.
83db04ff 318
a7154e91 319gitlink:git-revert[1]::
f85a4191
JH
320 Revert an existing commit.
321
a7154e91 322gitlink:git-shortlog[1]::
f85a4191
JH
323 Summarizes 'git log' output.
324
55258b5c
JL
325gitlink:git-show[1]::
326 Show one commit log and its diff.
327
a7154e91 328gitlink:git-show-branch[1]::
f85a4191
JH
329 Show branches and their commits.
330
a7154e91 331gitlink:git-status[1]::
f85a4191 332 Shows the working tree status.
83db04ff 333
a7154e91 334gitlink:git-verify-tag[1]::
905197de
JH
335 Check the GPG signature of tag.
336
a7154e91 337gitlink:git-whatchanged[1]::
f85a4191
JH
338 Shows commit logs and differences they introduce.
339
e31bb3bb 340
90933efb 341Ancillary Commands
23091e95 342~~~~~~~~~~~~~~~~~~
2f2de9b4
JH
343Manipulators:
344
a7154e91 345gitlink:git-applypatch[1]::
f85a4191 346 Apply one patch extracted from an e-mail.
905197de 347
a7154e91 348gitlink:git-archimport[1]::
5077fa9c
JH
349 Import an arch repository into git.
350
a7154e91 351gitlink:git-convert-objects[1]::
2fa090b6 352 Converts old-style git repository.
2f2de9b4 353
a7154e91 354gitlink:git-cvsimport[1]::
f85a4191
JH
355 Salvage your data out of another SCM people love to hate.
356
76cead39
JH
357gitlink:git-cvsexportcommit[1]::
358 Export a single commit to a CVS checkout.
359
0086e2c8 360gitlink:git-lost-found[1]::
04e7ca1a
JH
361 Recover lost refs that luckily have not yet been pruned.
362
a7154e91 363gitlink:git-merge-one-file[1]::
2fa090b6 364 The standard helper program to use with `git-merge-index`.
204ee6a9 365
a7154e91 366gitlink:git-prune[1]::
2fa090b6 367 Prunes all unreachable objects from the object database.
204ee6a9 368
a7154e91 369gitlink:git-relink[1]::
f85a4191
JH
370 Hardlink common objects in local repositories.
371
8548ea8d
PB
372gitlink:git-svnimport[1]::
373 Import a SVN repository into git.
374
a7154e91 375gitlink:git-sh-setup[1]::
f85a4191
JH
376 Common git shell script setup code.
377
a60d2d8f 378gitlink:git-symbolic-ref[1]::
2fa090b6 379 Read and modify symbolic refs.
a60d2d8f 380
a7154e91 381gitlink:git-tag[1]::
2fa090b6 382 An example script to create a tag object signed with GPG.
204ee6a9 383
8548ea8d
PB
384gitlink:git-update-ref[1]::
385 Update the object name stored in a ref safely.
386
204ee6a9 387
90933efb 388Interrogators:
204ee6a9 389
8548ea8d
PB
390gitlink:git-check-ref-format[1]::
391 Make sure ref name is well formed.
392
a7154e91 393gitlink:git-cherry[1]::
f85a4191 394 Find commits not merged upstream.
905197de 395
a7154e91 396gitlink:git-count-objects[1]::
905197de
JH
397 Count unpacked number of objects and their disk consumption.
398
a7154e91 399gitlink:git-daemon[1]::
72e9340c 400 A really simple server for git repositories.
5077fa9c 401
a7154e91 402gitlink:git-get-tar-commit-id[1]::
5077fa9c
JH
403 Extract commit ID from an archive created using git-tar-tree.
404
a7154e91 405gitlink:git-mailinfo[1]::
2fa090b6
JH
406 Extracts patch and authorship information from a single
407 e-mail message, optionally transliterating the commit
408 message into utf-8.
f85a4191 409
a7154e91 410gitlink:git-mailsplit[1]::
2fa090b6
JH
411 A stupid program to split UNIX mbox format mailbox into
412 individual pieces of e-mail.
f85a4191 413
a7154e91 414gitlink:git-patch-id[1]::
f85a4191 415 Compute unique ID for a patch.
204ee6a9 416
a7154e91 417gitlink:git-parse-remote[1]::
2fa090b6 418 Routines to help parsing `$GIT_DIR/remotes/` files.
5077fa9c 419
a7154e91 420gitlink:git-request-pull[1]::
215a7ad1 421 git-request-pull.
5077fa9c 422
a7154e91 423gitlink:git-rev-parse[1]::
5077fa9c
JH
424 Pick out and massage parameters.
425
a7154e91 426gitlink:git-send-email[1]::
83db04ff 427 Send patch e-mails out of "format-patch --mbox" output.
204ee6a9 428
c1fe2fe4 429gitlink:git-symbolic-ref[1]::
8548ea8d
PB
430 Read and modify symbolic refs.
431
a7154e91 432gitlink:git-stripspace[1]::
35ef3a4c 433 Filter out empty lines.
7fc9d69f 434
7fc9d69f 435
35ef3a4c
JH
436Commands not yet documented
437---------------------------
7fc9d69f 438
a7154e91 439gitlink:gitk[1]::
2fa090b6 440 The gitk repository browser.
7fc9d69f
JH
441
442
5773c9f2
JH
443Configuration Mechanism
444-----------------------
445
2fa090b6 446Starting from 0.99.9 (actually mid 0.99.8.GIT), `.git/config` file
5773c9f2
JH
447is used to hold per-repository configuration options. It is a
448simple text file modelled after `.ini` format familiar to some
449people. Here is an example:
450
451------------
452#
2fa090b6 453# A '#' or ';' character indicates a comment.
5773c9f2
JH
454#
455
456; core variables
457[core]
458 ; Don't trust file modes
459 filemode = false
460
461; user identity
462[user]
463 name = "Junio C Hamano"
464 email = "junkio@twinsun.com"
465
466------------
467
468Various commands read from the configuration file and adjust
469their operation accordingly.
470
471
6c84e2e0 472Identifier Terminology
2cf565c5
DG
473----------------------
474<object>::
2fa090b6 475 Indicates the object name for any type of object.
2cf565c5
DG
476
477<blob>::
2fa090b6 478 Indicates a blob object name.
2cf565c5
DG
479
480<tree>::
2fa090b6 481 Indicates a tree object name.
2cf565c5
DG
482
483<commit>::
2fa090b6 484 Indicates a commit object name.
2cf565c5
DG
485
486<tree-ish>::
2fa090b6 487 Indicates a tree, commit or tag object name. A
6c84e2e0
DG
488 command that takes a <tree-ish> argument ultimately wants to
489 operate on a <tree> object but automatically dereferences
490 <commit> and <tag> objects that point at a <tree>.
2cf565c5
DG
491
492<type>::
493 Indicates that an object type is required.
2fa090b6 494 Currently one of: `blob`, `tree`, `commit`, or `tag`.
2cf565c5
DG
495
496<file>::
2fa090b6
JH
497 Indicates a filename - almost always relative to the
498 root of the tree structure `GIT_INDEX_FILE` describes.
2cf565c5 499
c1bdacf9
DG
500Symbolic Identifiers
501--------------------
90933efb 502Any git command accepting any <object> can also use the following
6c84e2e0 503symbolic notation:
c1bdacf9
DG
504
505HEAD::
2fa090b6
JH
506 indicates the head of the current branch (i.e. the
507 contents of `$GIT_DIR/HEAD`).
508
c1bdacf9 509<tag>::
2fa090b6
JH
510 a valid tag 'name'
511 (i.e. the contents of `$GIT_DIR/refs/tags/<tag>`).
512
c1bdacf9 513<head>::
2fa090b6
JH
514 a valid head 'name'
515 (i.e. the contents of `$GIT_DIR/refs/heads/<head>`).
516
c1bdacf9
DG
517
518File/Directory Structure
519------------------------
c1bdacf9 520
a1d4aa74 521Please see link:repository-layout.html[repository layout] document.
c1bdacf9 522
6250ad1e
JL
523Read link:hooks.html[hooks] for more details about each hook.
524
c1bdacf9 525Higher level SCMs may provide and manage additional information in the
2fa090b6 526`$GIT_DIR`.
c1bdacf9 527
a1d4aa74 528
2cf565c5
DG
529Terminology
530-----------
1bff6490 531Please see link:glossary.html[glossary] document.
2cf565c5
DG
532
533
534Environment Variables
535---------------------
536Various git commands use the following environment variables:
537
c1bdacf9
DG
538The git Repository
539~~~~~~~~~~~~~~~~~~
540These environment variables apply to 'all' core git commands. Nb: it
541is worth noting that they may be used/overridden by SCMS sitting above
2fa090b6 542git so take care if using Cogito etc.
c1bdacf9
DG
543
544'GIT_INDEX_FILE'::
545 This environment allows the specification of an alternate
5f3aa197
LS
546 index file. If not specified, the default of `$GIT_DIR/index`
547 is used.
c1bdacf9
DG
548
549'GIT_OBJECT_DIRECTORY'::
550 If the object storage directory is specified via this
551 environment variable then the sha1 directories are created
552 underneath - otherwise the default `$GIT_DIR/objects`
553 directory is used.
554
555'GIT_ALTERNATE_OBJECT_DIRECTORIES'::
556 Due to the immutable nature of git objects, old objects can be
557 archived into shared, read-only directories. This variable
90933efb 558 specifies a ":" separated list of git object directories which
c1bdacf9
DG
559 can be used to search for git objects. New objects will not be
560 written to these directories.
561
562'GIT_DIR'::
2fa090b6
JH
563 If the 'GIT_DIR' environment variable is set then it
564 specifies a path to use instead of the default `.git`
565 for the base of the repository.
c1bdacf9
DG
566
567git Commits
568~~~~~~~~~~~
569'GIT_AUTHOR_NAME'::
570'GIT_AUTHOR_EMAIL'::
571'GIT_AUTHOR_DATE'::
572'GIT_COMMITTER_NAME'::
573'GIT_COMMITTER_EMAIL'::
a7154e91 574 see gitlink:git-commit-tree[1]
c1bdacf9
DG
575
576git Diffs
577~~~~~~~~~
d81ed1b5
JH
578'GIT_DIFF_OPTS'::
579'GIT_EXTERNAL_DIFF'::
c1bdacf9 580 see the "generating patches" section in :
a7154e91
SV
581 gitlink:git-diff-index[1];
582 gitlink:git-diff-files[1];
583 gitlink:git-diff-tree[1]
2cf565c5 584
8db9307c
JH
585Discussion[[Discussion]]
586------------------------
941c9449 587include::README[]
6c84e2e0 588
cb22bc44
AE
589Authors
590-------
9755afbd
JH
591* git's founding father is Linus Torvalds <torvalds@osdl.org>.
592* The current git nurse is Junio C Hamano <junkio@cox.net>.
593* The git potty was written by Andres Ericsson <ae@op5.se>.
594* General upbringing is handled by the git-list <git@vger.kernel.org>.
2cf565c5
DG
595
596Documentation
597--------------
9755afbd
JH
598The documentation for git suite was started by David Greaves
599<david@dgreaves.com>, and later enhanced greatly by the
600contributors on the git-list <git@vger.kernel.org>.
2cf565c5
DG
601
602GIT
603---
a7154e91 604Part of the gitlink:git[7] suite
2cf565c5 605