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