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