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