Documentation: more 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
a7154e91 162gitlink:git-rev-list[1]::
2fa090b6 163 Lists commit objects in reverse chronological order.
2cf565c5 164
a7154e91 165gitlink:git-show-index[1]::
f85a4191
JH
166 Displays contents of a pack idx file.
167
a7154e91 168gitlink:git-tar-tree[1]::
2fa090b6 169 Creates a tar archive of the files in the named tree object.
2cf565c5 170
a7154e91 171gitlink:git-unpack-file[1]::
2fa090b6 172 Creates a temporary file with a blob's contents.
2cf565c5 173
a7154e91 174gitlink:git-var[1]::
2fa090b6 175 Displays a git logical variable.
aed022ab 176
a7154e91 177gitlink:git-verify-pack[1]::
2fa090b6 178 Validates packed git archive files.
f9253394 179
2fa090b6
JH
180In general, the interrogate commands do not touch the files in
181the working tree.
2cf565c5
DG
182
183
0c04094b
JH
184Synching repositories
185~~~~~~~~~~~~~~~~~~~~~
186
a7154e91 187gitlink:git-clone-pack[1]::
6ec311da 188 Clones a repository into the current repository (engine
2fa090b6 189 for ssh and local transport).
6ec311da 190
a7154e91 191gitlink:git-fetch-pack[1]::
2fa090b6
JH
192 Updates from a remote repository (engine for ssh and
193 local transport).
f85a4191 194
a7154e91 195gitlink:git-http-fetch[1]::
2fa090b6
JH
196 Downloads a remote git repository via HTTP by walking
197 commit chain.
204ee6a9 198
a7154e91 199gitlink:git-local-fetch[1]::
2fa090b6
JH
200 Duplicates another git repository on a local system by
201 walking commit chain.
204ee6a9 202
a7154e91 203gitlink:git-peek-remote[1]::
2fa090b6
JH
204 Lists references on a remote repository using
205 upload-pack protocol (engine for ssh and local
206 transport).
2f2de9b4 207
a7154e91 208gitlink:git-receive-pack[1]::
2f2de9b4
JH
209 Invoked by 'git-send-pack' to receive what is pushed to it.
210
a7154e91 211gitlink:git-send-pack[1]::
f85a4191 212 Pushes to a remote repository, intelligently.
2f2de9b4 213
d43367af
PB
214gitlink:git-shell[1]::
215 Restricted shell for GIT-only SSH access.
216
a7154e91 217gitlink:git-ssh-fetch[1]::
2fa090b6
JH
218 Pulls from a remote repository over ssh connection by
219 walking commit chain.
508e67ab 220
a7154e91 221gitlink:git-ssh-upload[1]::
2fa090b6 222 Helper "server-side" program used by git-ssh-fetch.
2f2de9b4 223
a7154e91 224gitlink:git-update-server-info[1]::
61e3ef36
JH
225 Updates auxiliary information on a dumb server to help
226 clients discover references and packs on it.
227
a7154e91 228gitlink:git-upload-pack[1]::
f85a4191
JH
229 Invoked by 'git-clone-pack' and 'git-fetch-pack' to push
230 what are asked for.
231
2f2de9b4 232
3f971fc4
JH
233Porcelain-ish Commands
234----------------------
905197de 235
a7154e91 236gitlink:git-add[1]::
2fa090b6 237 Add paths to the index.
905197de 238
8548ea8d
PB
239gitlink:git-am[1]::
240 Apply patches from a mailbox, but cooler.
241
a7154e91 242gitlink:git-applymbox[1]::
2fa090b6 243 Apply patches from a mailbox, original version by Linus.
f85a4191 244
a7154e91 245gitlink:git-bisect[1]::
2fa090b6 246 Find the change that introduced a bug by binary search.
f85a4191 247
a7154e91 248gitlink:git-branch[1]::
905197de
JH
249 Create and Show branches.
250
a7154e91 251gitlink:git-checkout[1]::
452ce291
JH
252 Checkout and switch to a branch.
253
a7154e91 254gitlink:git-cherry-pick[1]::
f85a4191 255 Cherry-pick the effect of an existing commit.
3f971fc4 256
a7154e91 257gitlink:git-clone[1]::
f85a4191 258 Clones a repository into a new directory.
3f971fc4 259
a7154e91 260gitlink:git-commit[1]::
f85a4191 261 Record changes to the repository.
3f971fc4 262
a7154e91 263gitlink:git-diff[1]::
2aba319a 264 Show changes between commits, commit and working tree, etc.
35ef3a4c 265
a7154e91 266gitlink:git-fetch[1]::
62033318
JH
267 Download from a remote repository via various protocols.
268
a7154e91 269gitlink:git-format-patch[1]::
2aba319a 270 Prepare patches for e-mail submission.
35ef3a4c 271
a7154e91 272gitlink:git-grep[1]::
2fa090b6 273 Print lines matching a pattern.
2aba319a 274
a7154e91 275gitlink:git-log[1]::
f85a4191 276 Shows commit logs.
62033318 277
a7154e91 278gitlink:git-ls-remote[1]::
f85a4191 279 Shows references in a remote or local repository.
ab9b3138 280
a7154e91 281gitlink:git-merge[1]::
0f69be53
JH
282 Grand unified merge driver.
283
8548ea8d
PB
284gitlink:git-mv[1]::
285 Move or rename a file, a directory, or a symlink.
286
a7154e91 287gitlink:git-octopus[1]::
ab9b3138
JH
288 Merge more than two commits.
289
a7154e91 290gitlink:git-pull[1]::
f85a4191
JH
291 Fetch from and merge with a remote repository.
292
a7154e91 293gitlink:git-push[1]::
ab9b3138
JH
294 Update remote refs along with associated objects.
295
a7154e91 296gitlink:git-rebase[1]::
2fa090b6 297 Rebase local commits to the updated upstream head.
62033318 298
a7154e91 299gitlink:git-repack[1]::
e31bb3bb
JH
300 Pack unpacked objects in a repository.
301
a7154e91 302gitlink:git-reset[1]::
452ce291
JH
303 Reset current HEAD to the specified state.
304
a7154e91 305gitlink:git-resolve[1]::
f85a4191 306 Merge two commits.
83db04ff 307
a7154e91 308gitlink:git-revert[1]::
f85a4191
JH
309 Revert an existing commit.
310
a7154e91 311gitlink:git-shortlog[1]::
f85a4191
JH
312 Summarizes 'git log' output.
313
a7154e91 314gitlink:git-show-branch[1]::
f85a4191
JH
315 Show branches and their commits.
316
a7154e91 317gitlink:git-status[1]::
f85a4191 318 Shows the working tree status.
83db04ff 319
a7154e91 320gitlink:git-verify-tag[1]::
905197de
JH
321 Check the GPG signature of tag.
322
a7154e91 323gitlink:git-whatchanged[1]::
f85a4191
JH
324 Shows commit logs and differences they introduce.
325
e31bb3bb 326
90933efb
YS
327Ancillary Commands
328------------------
2f2de9b4
JH
329Manipulators:
330
a7154e91 331gitlink:git-applypatch[1]::
f85a4191 332 Apply one patch extracted from an e-mail.
905197de 333
a7154e91 334gitlink:git-archimport[1]::
5077fa9c
JH
335 Import an arch repository into git.
336
a7154e91 337gitlink:git-convert-objects[1]::
2fa090b6 338 Converts old-style git repository.
2f2de9b4 339
a7154e91 340gitlink:git-cvsimport[1]::
f85a4191
JH
341 Salvage your data out of another SCM people love to hate.
342
0086e2c8 343gitlink:git-lost-found[1]::
04e7ca1a
JH
344 Recover lost refs that luckily have not yet been pruned.
345
a7154e91 346gitlink:git-merge-one-file[1]::
2fa090b6 347 The standard helper program to use with `git-merge-index`.
204ee6a9 348
a7154e91 349gitlink:git-prune[1]::
2fa090b6 350 Prunes all unreachable objects from the object database.
204ee6a9 351
a7154e91 352gitlink:git-relink[1]::
f85a4191
JH
353 Hardlink common objects in local repositories.
354
8548ea8d
PB
355gitlink:git-svnimport[1]::
356 Import a SVN repository into git.
357
a7154e91 358gitlink:git-sh-setup[1]::
f85a4191
JH
359 Common git shell script setup code.
360
a60d2d8f 361gitlink:git-symbolic-ref[1]::
2fa090b6 362 Read and modify symbolic refs.
a60d2d8f 363
a7154e91 364gitlink:git-tag[1]::
2fa090b6 365 An example script to create a tag object signed with GPG.
204ee6a9 366
8548ea8d
PB
367gitlink:git-update-ref[1]::
368 Update the object name stored in a ref safely.
369
204ee6a9 370
90933efb 371Interrogators:
204ee6a9 372
8548ea8d
PB
373gitlink:git-check-ref-format[1]::
374 Make sure ref name is well formed.
375
a7154e91 376gitlink:git-cherry[1]::
f85a4191 377 Find commits not merged upstream.
905197de 378
a7154e91 379gitlink:git-count-objects[1]::
905197de
JH
380 Count unpacked number of objects and their disk consumption.
381
a7154e91 382gitlink:git-daemon[1]::
72e9340c 383 A really simple server for git repositories.
5077fa9c 384
a7154e91 385gitlink:git-get-tar-commit-id[1]::
5077fa9c
JH
386 Extract commit ID from an archive created using git-tar-tree.
387
a7154e91 388gitlink:git-mailinfo[1]::
2fa090b6
JH
389 Extracts patch and authorship information from a single
390 e-mail message, optionally transliterating the commit
391 message into utf-8.
f85a4191 392
a7154e91 393gitlink:git-mailsplit[1]::
2fa090b6
JH
394 A stupid program to split UNIX mbox format mailbox into
395 individual pieces of e-mail.
f85a4191 396
a7154e91 397gitlink:git-patch-id[1]::
f85a4191 398 Compute unique ID for a patch.
204ee6a9 399
a7154e91 400gitlink:git-parse-remote[1]::
2fa090b6 401 Routines to help parsing `$GIT_DIR/remotes/` files.
5077fa9c 402
a7154e91 403gitlink:git-request-pull[1]::
215a7ad1 404 git-request-pull.
5077fa9c 405
a7154e91 406gitlink:git-rev-parse[1]::
5077fa9c
JH
407 Pick out and massage parameters.
408
a7154e91 409gitlink:git-send-email[1]::
83db04ff 410 Send patch e-mails out of "format-patch --mbox" output.
204ee6a9 411
8548ea8d
PB
412gitlink:git-symbolic-refs[1]::
413 Read and modify symbolic refs.
414
a7154e91 415gitlink:git-stripspace[1]::
35ef3a4c 416 Filter out empty lines.
7fc9d69f 417
7fc9d69f 418
35ef3a4c
JH
419Commands not yet documented
420---------------------------
7fc9d69f 421
a7154e91 422gitlink:gitk[1]::
2fa090b6 423 The gitk repository browser.
7fc9d69f
JH
424
425
5773c9f2
JH
426Configuration Mechanism
427-----------------------
428
2fa090b6 429Starting from 0.99.9 (actually mid 0.99.8.GIT), `.git/config` file
5773c9f2
JH
430is used to hold per-repository configuration options. It is a
431simple text file modelled after `.ini` format familiar to some
432people. Here is an example:
433
434------------
435#
2fa090b6 436# A '#' or ';' character indicates a comment.
5773c9f2
JH
437#
438
439; core variables
440[core]
441 ; Don't trust file modes
442 filemode = false
443
444; user identity
445[user]
446 name = "Junio C Hamano"
447 email = "junkio@twinsun.com"
448
449------------
450
451Various commands read from the configuration file and adjust
452their operation accordingly.
453
454
6c84e2e0 455Identifier Terminology
2cf565c5
DG
456----------------------
457<object>::
2fa090b6 458 Indicates the object name for any type of object.
2cf565c5
DG
459
460<blob>::
2fa090b6 461 Indicates a blob object name.
2cf565c5
DG
462
463<tree>::
2fa090b6 464 Indicates a tree object name.
2cf565c5
DG
465
466<commit>::
2fa090b6 467 Indicates a commit object name.
2cf565c5
DG
468
469<tree-ish>::
2fa090b6 470 Indicates a tree, commit or tag object name. A
6c84e2e0
DG
471 command that takes a <tree-ish> argument ultimately wants to
472 operate on a <tree> object but automatically dereferences
473 <commit> and <tag> objects that point at a <tree>.
2cf565c5
DG
474
475<type>::
476 Indicates that an object type is required.
2fa090b6 477 Currently one of: `blob`, `tree`, `commit`, or `tag`.
2cf565c5
DG
478
479<file>::
2fa090b6
JH
480 Indicates a filename - almost always relative to the
481 root of the tree structure `GIT_INDEX_FILE` describes.
2cf565c5 482
c1bdacf9
DG
483Symbolic Identifiers
484--------------------
90933efb 485Any git command accepting any <object> can also use the following
6c84e2e0 486symbolic notation:
c1bdacf9
DG
487
488HEAD::
2fa090b6
JH
489 indicates the head of the current branch (i.e. the
490 contents of `$GIT_DIR/HEAD`).
491
c1bdacf9 492<tag>::
2fa090b6
JH
493 a valid tag 'name'
494 (i.e. the contents of `$GIT_DIR/refs/tags/<tag>`).
495
c1bdacf9 496<head>::
2fa090b6
JH
497 a valid head 'name'
498 (i.e. the contents of `$GIT_DIR/refs/heads/<head>`).
499
c1bdacf9 500<snap>::
2fa090b6
JH
501 a valid snapshot 'name'
502 (i.e. the contents of `$GIT_DIR/refs/snap/<snap>`).
c1bdacf9
DG
503
504
505File/Directory Structure
506------------------------
c1bdacf9 507
a1d4aa74 508Please see link:repository-layout.html[repository layout] document.
c1bdacf9
DG
509
510Higher level SCMs may provide and manage additional information in the
2fa090b6 511`$GIT_DIR`.
c1bdacf9 512
a1d4aa74 513
2cf565c5
DG
514Terminology
515-----------
1bff6490 516Please see link:glossary.html[glossary] document.
2cf565c5
DG
517
518
519Environment Variables
520---------------------
521Various git commands use the following environment variables:
522
c1bdacf9
DG
523The git Repository
524~~~~~~~~~~~~~~~~~~
525These environment variables apply to 'all' core git commands. Nb: it
526is worth noting that they may be used/overridden by SCMS sitting above
2fa090b6 527git so take care if using Cogito etc.
c1bdacf9
DG
528
529'GIT_INDEX_FILE'::
530 This environment allows the specification of an alternate
5f3aa197
LS
531 index file. If not specified, the default of `$GIT_DIR/index`
532 is used.
c1bdacf9
DG
533
534'GIT_OBJECT_DIRECTORY'::
535 If the object storage directory is specified via this
536 environment variable then the sha1 directories are created
537 underneath - otherwise the default `$GIT_DIR/objects`
538 directory is used.
539
540'GIT_ALTERNATE_OBJECT_DIRECTORIES'::
541 Due to the immutable nature of git objects, old objects can be
542 archived into shared, read-only directories. This variable
90933efb 543 specifies a ":" separated list of git object directories which
c1bdacf9
DG
544 can be used to search for git objects. New objects will not be
545 written to these directories.
546
547'GIT_DIR'::
2fa090b6
JH
548 If the 'GIT_DIR' environment variable is set then it
549 specifies a path to use instead of the default `.git`
550 for the base of the repository.
c1bdacf9
DG
551
552git Commits
553~~~~~~~~~~~
554'GIT_AUTHOR_NAME'::
555'GIT_AUTHOR_EMAIL'::
556'GIT_AUTHOR_DATE'::
557'GIT_COMMITTER_NAME'::
558'GIT_COMMITTER_EMAIL'::
a7154e91 559 see gitlink:git-commit-tree[1]
c1bdacf9
DG
560
561git Diffs
562~~~~~~~~~
d81ed1b5
JH
563'GIT_DIFF_OPTS'::
564'GIT_EXTERNAL_DIFF'::
c1bdacf9 565 see the "generating patches" section in :
a7154e91
SV
566 gitlink:git-diff-index[1];
567 gitlink:git-diff-files[1];
568 gitlink:git-diff-tree[1]
2cf565c5 569
8db9307c
JH
570Discussion[[Discussion]]
571------------------------
6c84e2e0
DG
572include::../README[]
573
cb22bc44
AE
574Authors
575-------
576 git's founding father is Linus Torvalds <torvalds@osdl.org>.
2fa090b6 577 The current git nurse is Junio C Hamano <junkio@cox.net>.
cb22bc44
AE
578 The git potty was written by Andres Ericsson <ae@op5.se>.
579 General upbringing is handled by the git-list <git@vger.kernel.org>.
2cf565c5
DG
580
581Documentation
582--------------
583Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
584
585GIT
586---
a7154e91 587Part of the gitlink:git[7] suite
2cf565c5 588