sample update-hook: sanely handle a new branch head.
[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
a7154e91 316gitlink:git-reset[1]::
452ce291
JH
317 Reset current HEAD to the specified state.
318
a7154e91 319gitlink:git-resolve[1]::
f85a4191 320 Merge two commits.
83db04ff 321
a7154e91 322gitlink:git-revert[1]::
f85a4191
JH
323 Revert an existing commit.
324
a7154e91 325gitlink:git-shortlog[1]::
f85a4191
JH
326 Summarizes 'git log' output.
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
YS
341Ancillary Commands
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 517<snap>::
2fa090b6
JH
518 a valid snapshot 'name'
519 (i.e. the contents of `$GIT_DIR/refs/snap/<snap>`).
c1bdacf9
DG
520
521
522File/Directory Structure
523------------------------
c1bdacf9 524
a1d4aa74 525Please see link:repository-layout.html[repository layout] document.
c1bdacf9
DG
526
527Higher level SCMs may provide and manage additional information in the
2fa090b6 528`$GIT_DIR`.
c1bdacf9 529
a1d4aa74 530
2cf565c5
DG
531Terminology
532-----------
1bff6490 533Please see link:glossary.html[glossary] document.
2cf565c5
DG
534
535
536Environment Variables
537---------------------
538Various git commands use the following environment variables:
539
c1bdacf9
DG
540The git Repository
541~~~~~~~~~~~~~~~~~~
542These environment variables apply to 'all' core git commands. Nb: it
543is worth noting that they may be used/overridden by SCMS sitting above
2fa090b6 544git so take care if using Cogito etc.
c1bdacf9
DG
545
546'GIT_INDEX_FILE'::
547 This environment allows the specification of an alternate
5f3aa197
LS
548 index file. If not specified, the default of `$GIT_DIR/index`
549 is used.
c1bdacf9
DG
550
551'GIT_OBJECT_DIRECTORY'::
552 If the object storage directory is specified via this
553 environment variable then the sha1 directories are created
554 underneath - otherwise the default `$GIT_DIR/objects`
555 directory is used.
556
557'GIT_ALTERNATE_OBJECT_DIRECTORIES'::
558 Due to the immutable nature of git objects, old objects can be
559 archived into shared, read-only directories. This variable
90933efb 560 specifies a ":" separated list of git object directories which
c1bdacf9
DG
561 can be used to search for git objects. New objects will not be
562 written to these directories.
563
564'GIT_DIR'::
2fa090b6
JH
565 If the 'GIT_DIR' environment variable is set then it
566 specifies a path to use instead of the default `.git`
567 for the base of the repository.
c1bdacf9
DG
568
569git Commits
570~~~~~~~~~~~
571'GIT_AUTHOR_NAME'::
572'GIT_AUTHOR_EMAIL'::
573'GIT_AUTHOR_DATE'::
574'GIT_COMMITTER_NAME'::
575'GIT_COMMITTER_EMAIL'::
a7154e91 576 see gitlink:git-commit-tree[1]
c1bdacf9
DG
577
578git Diffs
579~~~~~~~~~
d81ed1b5
JH
580'GIT_DIFF_OPTS'::
581'GIT_EXTERNAL_DIFF'::
c1bdacf9 582 see the "generating patches" section in :
a7154e91
SV
583 gitlink:git-diff-index[1];
584 gitlink:git-diff-files[1];
585 gitlink:git-diff-tree[1]
2cf565c5 586
8db9307c
JH
587Discussion[[Discussion]]
588------------------------
6c84e2e0
DG
589include::../README[]
590
cb22bc44
AE
591Authors
592-------
9755afbd
JH
593* git's founding father is Linus Torvalds <torvalds@osdl.org>.
594* The current git nurse is Junio C Hamano <junkio@cox.net>.
595* The git potty was written by Andres Ericsson <ae@op5.se>.
596* General upbringing is handled by the git-list <git@vger.kernel.org>.
2cf565c5
DG
597
598Documentation
599--------------
9755afbd
JH
600The documentation for git suite was started by David Greaves
601<david@dgreaves.com>, and later enhanced greatly by the
602contributors on the git-list <git@vger.kernel.org>.
2cf565c5
DG
603
604GIT
605---
a7154e91 606Part of the gitlink:git[7] suite
2cf565c5 607