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