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