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