blame: Fix git-blame <directory>
[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
a7154e91 332gitlink:git-show-branch[1]::
f85a4191
JH
333 Show branches and their commits.
334
a7154e91 335gitlink:git-status[1]::
f85a4191 336 Shows the working tree status.
83db04ff 337
a7154e91 338gitlink:git-verify-tag[1]::
905197de
JH
339 Check the GPG signature of tag.
340
a7154e91 341gitlink:git-whatchanged[1]::
f85a4191
JH
342 Shows commit logs and differences they introduce.
343
e31bb3bb 344
90933efb
YS
345Ancillary Commands
346------------------
2f2de9b4
JH
347Manipulators:
348
a7154e91 349gitlink:git-applypatch[1]::
f85a4191 350 Apply one patch extracted from an e-mail.
905197de 351
a7154e91 352gitlink:git-archimport[1]::
5077fa9c
JH
353 Import an arch repository into git.
354
a7154e91 355gitlink:git-convert-objects[1]::
2fa090b6 356 Converts old-style git repository.
2f2de9b4 357
a7154e91 358gitlink:git-cvsimport[1]::
f85a4191
JH
359 Salvage your data out of another SCM people love to hate.
360
76cead39
JH
361gitlink:git-cvsexportcommit[1]::
362 Export a single commit to a CVS checkout.
363
0086e2c8 364gitlink:git-lost-found[1]::
04e7ca1a
JH
365 Recover lost refs that luckily have not yet been pruned.
366
a7154e91 367gitlink:git-merge-one-file[1]::
2fa090b6 368 The standard helper program to use with `git-merge-index`.
204ee6a9 369
a7154e91 370gitlink:git-prune[1]::
2fa090b6 371 Prunes all unreachable objects from the object database.
204ee6a9 372
a7154e91 373gitlink:git-relink[1]::
f85a4191
JH
374 Hardlink common objects in local repositories.
375
8548ea8d
PB
376gitlink:git-svnimport[1]::
377 Import a SVN repository into git.
378
a7154e91 379gitlink:git-sh-setup[1]::
f85a4191
JH
380 Common git shell script setup code.
381
a60d2d8f 382gitlink:git-symbolic-ref[1]::
2fa090b6 383 Read and modify symbolic refs.
a60d2d8f 384
a7154e91 385gitlink:git-tag[1]::
2fa090b6 386 An example script to create a tag object signed with GPG.
204ee6a9 387
8548ea8d
PB
388gitlink:git-update-ref[1]::
389 Update the object name stored in a ref safely.
390
204ee6a9 391
90933efb 392Interrogators:
204ee6a9 393
8548ea8d
PB
394gitlink:git-check-ref-format[1]::
395 Make sure ref name is well formed.
396
a7154e91 397gitlink:git-cherry[1]::
f85a4191 398 Find commits not merged upstream.
905197de 399
a7154e91 400gitlink:git-count-objects[1]::
905197de
JH
401 Count unpacked number of objects and their disk consumption.
402
a7154e91 403gitlink:git-daemon[1]::
72e9340c 404 A really simple server for git repositories.
5077fa9c 405
a7154e91 406gitlink:git-get-tar-commit-id[1]::
5077fa9c
JH
407 Extract commit ID from an archive created using git-tar-tree.
408
a7154e91 409gitlink:git-mailinfo[1]::
2fa090b6
JH
410 Extracts patch and authorship information from a single
411 e-mail message, optionally transliterating the commit
412 message into utf-8.
f85a4191 413
a7154e91 414gitlink:git-mailsplit[1]::
2fa090b6
JH
415 A stupid program to split UNIX mbox format mailbox into
416 individual pieces of e-mail.
f85a4191 417
a7154e91 418gitlink:git-patch-id[1]::
f85a4191 419 Compute unique ID for a patch.
204ee6a9 420
a7154e91 421gitlink:git-parse-remote[1]::
2fa090b6 422 Routines to help parsing `$GIT_DIR/remotes/` files.
5077fa9c 423
a7154e91 424gitlink:git-request-pull[1]::
215a7ad1 425 git-request-pull.
5077fa9c 426
a7154e91 427gitlink:git-rev-parse[1]::
5077fa9c
JH
428 Pick out and massage parameters.
429
a7154e91 430gitlink:git-send-email[1]::
83db04ff 431 Send patch e-mails out of "format-patch --mbox" output.
204ee6a9 432
c1fe2fe4 433gitlink:git-symbolic-ref[1]::
8548ea8d
PB
434 Read and modify symbolic refs.
435
a7154e91 436gitlink:git-stripspace[1]::
35ef3a4c 437 Filter out empty lines.
7fc9d69f 438
7fc9d69f 439
35ef3a4c
JH
440Commands not yet documented
441---------------------------
7fc9d69f 442
a7154e91 443gitlink:gitk[1]::
2fa090b6 444 The gitk repository browser.
7fc9d69f
JH
445
446
5773c9f2
JH
447Configuration Mechanism
448-----------------------
449
2fa090b6 450Starting from 0.99.9 (actually mid 0.99.8.GIT), `.git/config` file
5773c9f2
JH
451is used to hold per-repository configuration options. It is a
452simple text file modelled after `.ini` format familiar to some
453people. Here is an example:
454
455------------
456#
2fa090b6 457# A '#' or ';' character indicates a comment.
5773c9f2
JH
458#
459
460; core variables
461[core]
462 ; Don't trust file modes
463 filemode = false
464
465; user identity
466[user]
467 name = "Junio C Hamano"
468 email = "junkio@twinsun.com"
469
470------------
471
472Various commands read from the configuration file and adjust
473their operation accordingly.
474
475
6c84e2e0 476Identifier Terminology
2cf565c5
DG
477----------------------
478<object>::
2fa090b6 479 Indicates the object name for any type of object.
2cf565c5
DG
480
481<blob>::
2fa090b6 482 Indicates a blob object name.
2cf565c5
DG
483
484<tree>::
2fa090b6 485 Indicates a tree object name.
2cf565c5
DG
486
487<commit>::
2fa090b6 488 Indicates a commit object name.
2cf565c5
DG
489
490<tree-ish>::
2fa090b6 491 Indicates a tree, commit or tag object name. A
6c84e2e0
DG
492 command that takes a <tree-ish> argument ultimately wants to
493 operate on a <tree> object but automatically dereferences
494 <commit> and <tag> objects that point at a <tree>.
2cf565c5
DG
495
496<type>::
497 Indicates that an object type is required.
2fa090b6 498 Currently one of: `blob`, `tree`, `commit`, or `tag`.
2cf565c5
DG
499
500<file>::
2fa090b6
JH
501 Indicates a filename - almost always relative to the
502 root of the tree structure `GIT_INDEX_FILE` describes.
2cf565c5 503
c1bdacf9
DG
504Symbolic Identifiers
505--------------------
90933efb 506Any git command accepting any <object> can also use the following
6c84e2e0 507symbolic notation:
c1bdacf9
DG
508
509HEAD::
2fa090b6
JH
510 indicates the head of the current branch (i.e. the
511 contents of `$GIT_DIR/HEAD`).
512
c1bdacf9 513<tag>::
2fa090b6
JH
514 a valid tag 'name'
515 (i.e. the contents of `$GIT_DIR/refs/tags/<tag>`).
516
c1bdacf9 517<head>::
2fa090b6
JH
518 a valid head 'name'
519 (i.e. the contents of `$GIT_DIR/refs/heads/<head>`).
520
c1bdacf9 521<snap>::
2fa090b6
JH
522 a valid snapshot 'name'
523 (i.e. the contents of `$GIT_DIR/refs/snap/<snap>`).
c1bdacf9
DG
524
525
526File/Directory Structure
527------------------------
c1bdacf9 528
a1d4aa74 529Please see link:repository-layout.html[repository layout] document.
c1bdacf9
DG
530
531Higher level SCMs may provide and manage additional information in the
2fa090b6 532`$GIT_DIR`.
c1bdacf9 533
a1d4aa74 534
2cf565c5
DG
535Terminology
536-----------
1bff6490 537Please see link:glossary.html[glossary] document.
2cf565c5
DG
538
539
540Environment Variables
541---------------------
542Various git commands use the following environment variables:
543
c1bdacf9
DG
544The git Repository
545~~~~~~~~~~~~~~~~~~
546These environment variables apply to 'all' core git commands. Nb: it
547is worth noting that they may be used/overridden by SCMS sitting above
2fa090b6 548git so take care if using Cogito etc.
c1bdacf9
DG
549
550'GIT_INDEX_FILE'::
551 This environment allows the specification of an alternate
5f3aa197
LS
552 index file. If not specified, the default of `$GIT_DIR/index`
553 is used.
c1bdacf9
DG
554
555'GIT_OBJECT_DIRECTORY'::
556 If the object storage directory is specified via this
557 environment variable then the sha1 directories are created
558 underneath - otherwise the default `$GIT_DIR/objects`
559 directory is used.
560
561'GIT_ALTERNATE_OBJECT_DIRECTORIES'::
562 Due to the immutable nature of git objects, old objects can be
563 archived into shared, read-only directories. This variable
90933efb 564 specifies a ":" separated list of git object directories which
c1bdacf9
DG
565 can be used to search for git objects. New objects will not be
566 written to these directories.
567
568'GIT_DIR'::
2fa090b6
JH
569 If the 'GIT_DIR' environment variable is set then it
570 specifies a path to use instead of the default `.git`
571 for the base of the repository.
c1bdacf9
DG
572
573git Commits
574~~~~~~~~~~~
575'GIT_AUTHOR_NAME'::
576'GIT_AUTHOR_EMAIL'::
577'GIT_AUTHOR_DATE'::
578'GIT_COMMITTER_NAME'::
579'GIT_COMMITTER_EMAIL'::
a7154e91 580 see gitlink:git-commit-tree[1]
c1bdacf9
DG
581
582git Diffs
583~~~~~~~~~
d81ed1b5
JH
584'GIT_DIFF_OPTS'::
585'GIT_EXTERNAL_DIFF'::
c1bdacf9 586 see the "generating patches" section in :
a7154e91
SV
587 gitlink:git-diff-index[1];
588 gitlink:git-diff-files[1];
589 gitlink:git-diff-tree[1]
2cf565c5 590
8db9307c
JH
591Discussion[[Discussion]]
592------------------------
941c9449 593include::README[]
6c84e2e0 594
cb22bc44
AE
595Authors
596-------
9755afbd
JH
597* git's founding father is Linus Torvalds <torvalds@osdl.org>.
598* The current git nurse is Junio C Hamano <junkio@cox.net>.
599* The git potty was written by Andres Ericsson <ae@op5.se>.
600* General upbringing is handled by the git-list <git@vger.kernel.org>.
2cf565c5
DG
601
602Documentation
603--------------
9755afbd
JH
604The documentation for git suite was started by David Greaves
605<david@dgreaves.com>, and later enhanced greatly by the
606contributors on the git-list <git@vger.kernel.org>.
2cf565c5
DG
607
608GIT
609---
a7154e91 610Part of the gitlink:git[7] suite
2cf565c5 611