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