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