Merge branch 'lt/grep'
[git.git] / Documentation / git.txt
1 git(7)
2 ======
3
4 NAME
5 ----
6 git - the stupid content tracker
7
8
9 SYNOPSIS
10 --------
11 'git' [--version] [--exec-path[=GIT_EXEC_PATH]] [--help] COMMAND [ARGS]
12
13 DESCRIPTION
14 -----------
15 Git is a fast, scalable, distributed revision control system with an
16 unusually rich command set that provides both high-level operations
17 and full access to internals.
18
19 See this link:tutorial.html[tutorial] to get started, then see
20 link:everyday.html[Everyday Git] for a useful minimum set of commands, and
21 "man git-commandname" for documentation of each command.  CVS users may
22 also want to read link:cvs-migration.html[CVS migration].
23
24 OPTIONS
25 -------
26 --version::
27         Prints the git suite version that the 'git' program came from.
28
29 --help::
30         Prints the synopsis and a list of the most commonly used
31         commands.  If a git command is named this option will bring up
32         the man-page for that command. If the option '--all' or '-a' is
33         given then all available commands are printed.
34
35 --exec-path::
36         Path to wherever your core git programs are installed.
37         This can also be controlled by setting the GIT_EXEC_PATH
38         environment variable. If no path is given 'git' will print
39         the current setting and then exit.
40
41
42 FURTHER DOCUMENTATION
43 ---------------------
44
45 See the references above to get started using git.  The following is
46 probably more detail than necessary for a first-time user.
47
48 The <<Discussion,Discussion>> section below and the
49 link:core-tutorial.html[Core tutorial] both provide introductions to the
50 underlying git architecture.
51
52 See also the link:howto-index.html[howto] documents for some useful
53 examples.
54
55 GIT COMMANDS
56 ------------
57
58 We divide git into high level ("porcelain") commands and low level
59 ("plumbing") commands.
60
61 Low-level commands (plumbing)
62 -----------------------------
63
64 Although git includes its
65 own porcelain layer, its low-level commands are sufficient to support
66 development of alternative porcelains.  Developers of such porcelains
67 might start by reading about gitlink:git-update-index[1] and
68 gitlink:git-read-tree[1].
69
70 We divide the low-level commands into commands that manipulate objects (in
71 the repository, index, and working tree), commands that interrogate and
72 compare objects, and commands that move objects and references between
73 repositories.
74
75 Manipulation commands
76 ~~~~~~~~~~~~~~~~~~~~~
77 gitlink:git-apply[1]::
78         Reads a "diff -up1" or git generated patch file and
79         applies it to the working tree.
80
81 gitlink:git-checkout-index[1]::
82         Copy files from the index to the working tree.
83
84 gitlink:git-commit-tree[1]::
85         Creates a new commit object.
86
87 gitlink:git-hash-object[1]::
88         Computes the object ID from a file.
89
90 gitlink:git-index-pack[1]::
91         Build pack idx file for an existing packed archive.
92
93 gitlink:git-init-db[1]::
94         Creates an empty git object database, or reinitialize an
95         existing one.
96
97 gitlink:git-merge-index[1]::
98         Runs a merge for files needing merging.
99
100 gitlink:git-mktag[1]::
101         Creates a tag object.
102
103 gitlink:git-mktree[1]::
104         Build a tree-object from ls-tree formatted text.
105
106 gitlink:git-pack-objects[1]::
107         Creates a packed archive of objects.
108
109 gitlink:git-prune-packed[1]::
110         Remove extra objects that are already in pack files.
111
112 gitlink:git-read-tree[1]::
113         Reads tree information into the index.
114
115 gitlink:git-repo-config[1]::
116         Get and set options in .git/config.
117
118 gitlink:git-unpack-objects[1]::
119         Unpacks objects out of a packed archive.
120
121 gitlink:git-update-index[1]::
122         Registers files in the working tree to the index.
123
124 gitlink:git-write-tree[1]::
125         Creates a tree from the index.
126
127
128 Interrogation commands
129 ~~~~~~~~~~~~~~~~~~~~~~
130
131 gitlink:git-cat-file[1]::
132         Provide content or type/size information for repository objects.
133
134 gitlink:git-describe[1]::
135         Show the most recent tag that is reachable from a commit.
136
137 gitlink:git-diff-index[1]::
138         Compares content and mode of blobs between the index and repository.
139
140 gitlink:git-diff-files[1]::
141         Compares files in the working tree and the index.
142
143 gitlink:git-diff-stages[1]::
144         Compares two "merge stages" in the index.
145
146 gitlink:git-diff-tree[1]::
147         Compares the content and mode of blobs found via two tree objects.
148
149 gitlink:git-fsck-objects[1]::
150         Verifies the connectivity and validity of the objects in the database.
151
152 gitlink:git-ls-files[1]::
153         Information about files in the index and the working tree.
154
155 gitlink:git-ls-tree[1]::
156         Displays a tree object in human readable form.
157
158 gitlink:git-merge-base[1]::
159         Finds as good common ancestors as possible for a merge.
160
161 gitlink:git-name-rev[1]::
162         Find symbolic names for given revs.
163
164 gitlink:git-pack-redundant[1]::
165         Find redundant pack files.
166
167 gitlink:git-rev-list[1]::
168         Lists commit objects in reverse chronological order.
169
170 gitlink:git-show-index[1]::
171         Displays contents of a pack idx file.
172
173 gitlink:git-tar-tree[1]::
174         Creates a tar archive of the files in the named tree object.
175
176 gitlink:git-unpack-file[1]::
177         Creates a temporary file with a blob's contents.
178
179 gitlink:git-var[1]::
180         Displays a git logical variable.
181
182 gitlink:git-verify-pack[1]::
183         Validates packed git archive files.
184
185 In general, the interrogate commands do not touch the files in
186 the working tree.
187
188
189 Synching repositories
190 ~~~~~~~~~~~~~~~~~~~~~
191
192 gitlink:git-clone-pack[1]::
193         Clones a repository into the current repository (engine
194         for ssh and local transport).
195
196 gitlink:git-fetch-pack[1]::
197         Updates from a remote repository (engine for ssh and
198         local transport).
199
200 gitlink:git-http-fetch[1]::
201         Downloads a remote git repository via HTTP by walking
202         commit chain.
203
204 gitlink:git-local-fetch[1]::
205         Duplicates another git repository on a local system by
206         walking commit chain.
207
208 gitlink:git-peek-remote[1]::
209         Lists references on a remote repository using
210         upload-pack protocol (engine for ssh and local
211         transport).
212
213 gitlink:git-receive-pack[1]::
214         Invoked by 'git-send-pack' to receive what is pushed to it.
215
216 gitlink:git-send-pack[1]::
217         Pushes to a remote repository, intelligently.
218
219 gitlink:git-http-push[1]::
220         Push missing objects using HTTP/DAV.
221
222 gitlink:git-shell[1]::
223         Restricted shell for GIT-only SSH access.
224
225 gitlink:git-ssh-fetch[1]::
226         Pulls from a remote repository over ssh connection by
227         walking commit chain.
228
229 gitlink:git-ssh-upload[1]::
230         Helper "server-side" program used by git-ssh-fetch.
231
232 gitlink:git-update-server-info[1]::
233         Updates auxiliary information on a dumb server to help
234         clients discover references and packs on it.
235
236 gitlink:git-upload-pack[1]::
237         Invoked by 'git-clone-pack' and 'git-fetch-pack' to push
238         what are asked for.
239
240
241 High-level commands (porcelain)
242 -------------------------------
243
244 We separate the porcelain commands into the main commands and some
245 ancillary user utilities.
246
247 Main porcelain commands
248 ~~~~~~~~~~~~~~~~~~~~~~~
249
250 gitlink:git-add[1]::
251         Add paths to the index.
252
253 gitlink:git-am[1]::
254         Apply patches from a mailbox, but cooler.
255
256 gitlink:git-applymbox[1]::
257         Apply patches from a mailbox, original version by Linus.
258
259 gitlink:git-bisect[1]::
260         Find the change that introduced a bug by binary search.
261
262 gitlink:git-branch[1]::
263         Create and Show branches.
264
265 gitlink:git-checkout[1]::
266         Checkout and switch to a branch.
267
268 gitlink:git-cherry-pick[1]::
269         Cherry-pick the effect of an existing commit.
270
271 gitlink:git-clean[1]::
272         Remove untracked files from the working tree.
273
274 gitlink:git-clone[1]::
275         Clones a repository into a new directory.
276
277 gitlink:git-commit[1]::
278         Record changes to the repository.
279
280 gitlink:git-diff[1]::
281         Show changes between commits, commit and working tree, etc.
282
283 gitlink:git-fetch[1]::
284         Download from a remote repository via various protocols.
285
286 gitlink:git-format-patch[1]::
287         Prepare patches for e-mail submission.
288
289 gitlink:git-grep[1]::
290         Print lines matching a pattern.
291
292 gitlink:git-log[1]::
293         Shows commit logs.
294
295 gitlink:git-ls-remote[1]::
296         Shows references in a remote or local repository.
297
298 gitlink:git-merge[1]::
299         Grand unified merge driver.
300
301 gitlink:git-mv[1]::
302         Move or rename a file, a directory, or a symlink.
303
304 gitlink:git-pull[1]::
305         Fetch from and merge with a remote repository.
306
307 gitlink:git-push[1]::
308         Update remote refs along with associated objects.
309
310 gitlink:git-rebase[1]::
311         Rebase local commits to the updated upstream head.
312
313 gitlink:git-repack[1]::
314         Pack unpacked objects in a repository.
315
316 gitlink:git-rerere[1]::
317         Reuse recorded resolution of conflicted merges.
318
319 gitlink:git-reset[1]::
320         Reset current HEAD to the specified state.
321
322 gitlink:git-resolve[1]::
323         Merge two commits.
324
325 gitlink:git-revert[1]::
326         Revert an existing commit.
327
328 gitlink:git-rm[1]::
329         Remove files from the working tree and from the index.
330
331 gitlink:git-shortlog[1]::
332         Summarizes 'git log' output.
333
334 gitlink:git-show[1]::
335         Show one commit log and its diff.
336
337 gitlink:git-show-branch[1]::
338         Show branches and their commits.
339
340 gitlink:git-status[1]::
341         Shows the working tree status.
342
343 gitlink:git-verify-tag[1]::
344         Check the GPG signature of tag.
345
346 gitlink:git-whatchanged[1]::
347         Shows commit logs and differences they introduce.
348
349
350 Ancillary Commands
351 ~~~~~~~~~~~~~~~~~~
352 Manipulators:
353
354 gitlink:git-applypatch[1]::
355         Apply one patch extracted from an e-mail.
356
357 gitlink:git-archimport[1]::
358         Import an arch repository into git.
359
360 gitlink:git-convert-objects[1]::
361         Converts old-style git repository.
362
363 gitlink:git-cvsimport[1]::
364         Salvage your data out of another SCM people love to hate.
365
366 gitlink:git-cvsexportcommit[1]::
367         Export a single commit to a CVS checkout.
368
369 gitlink:git-cvsserver[1]::
370         A CVS server emulator for git.
371
372 gitlink:git-lost-found[1]::
373         Recover lost refs that luckily have not yet been pruned.
374
375 gitlink:git-merge-one-file[1]::
376         The standard helper program to use with `git-merge-index`.
377
378 gitlink:git-prune[1]::
379         Prunes all unreachable objects from the object database.
380
381 gitlink:git-relink[1]::
382         Hardlink common objects in local repositories.
383
384 gitlink:git-svnimport[1]::
385         Import a SVN repository into git.
386
387 gitlink:git-sh-setup[1]::
388         Common git shell script setup code.
389
390 gitlink:git-symbolic-ref[1]::
391         Read and modify symbolic refs.
392
393 gitlink:git-tag[1]::
394         An example script to create a tag object signed with GPG.
395
396 gitlink:git-update-ref[1]::
397         Update the object name stored in a ref safely.
398
399
400 Interrogators:
401
402 gitlink:git-annotate[1]::
403         Annotate file lines with commit info.
404
405 gitlink:git-blame[1]::
406         Blame file lines on commits.
407
408 gitlink:git-check-ref-format[1]::
409         Make sure ref name is well formed.
410
411 gitlink:git-cherry[1]::
412         Find commits not merged upstream.
413
414 gitlink:git-count-objects[1]::
415         Count unpacked number of objects and their disk consumption.
416
417 gitlink:git-daemon[1]::
418         A really simple server for git repositories.
419
420 gitlink:git-fmt-merge-msg[1]::
421         Produce a merge commit message.
422
423 gitlink:git-get-tar-commit-id[1]::
424         Extract commit ID from an archive created using git-tar-tree.
425
426 gitlink:git-imap-send[1]::
427         Dump a mailbox from stdin into an imap folder.
428
429 gitlink:git-mailinfo[1]::
430         Extracts patch and authorship information from a single
431         e-mail message, optionally transliterating the commit
432         message into utf-8.
433
434 gitlink:git-mailsplit[1]::
435         A stupid program to split UNIX mbox format mailbox into
436         individual pieces of e-mail.
437
438 gitlink:git-merge-tree[1]::
439         Show three-way merge without touching index.
440
441 gitlink:git-patch-id[1]::
442         Compute unique ID for a patch.
443
444 gitlink:git-parse-remote[1]::
445         Routines to help parsing `$GIT_DIR/remotes/` files.
446
447 gitlink:git-request-pull[1]::
448         git-request-pull.
449
450 gitlink:git-rev-parse[1]::
451         Pick out and massage parameters.
452
453 gitlink:git-send-email[1]::
454         Send patch e-mails out of "format-patch --mbox" output.
455
456 gitlink:git-symbolic-ref[1]::
457         Read and modify symbolic refs.
458
459 gitlink:git-stripspace[1]::
460         Filter out empty lines.
461
462
463 Commands not yet documented
464 ---------------------------
465
466 gitlink:gitk[1]::
467         The gitk repository browser.
468
469
470 Configuration Mechanism
471 -----------------------
472
473 Starting from 0.99.9 (actually mid 0.99.8.GIT), `.git/config` file
474 is used to hold per-repository configuration options.  It is a
475 simple text file modelled after `.ini` format familiar to some
476 people.  Here is an example:
477
478 ------------
479 #
480 # A '#' or ';' character indicates a comment.
481 #
482
483 ; core variables
484 [core]
485         ; Don't trust file modes
486         filemode = false
487
488 ; user identity
489 [user]
490         name = "Junio C Hamano"
491         email = "junkio@twinsun.com"
492
493 ------------
494
495 Various commands read from the configuration file and adjust
496 their operation accordingly.
497
498
499 Identifier Terminology
500 ----------------------
501 <object>::
502         Indicates the object name for any type of object.
503
504 <blob>::
505         Indicates a blob object name.
506
507 <tree>::
508         Indicates a tree object name.
509
510 <commit>::
511         Indicates a commit object name.
512
513 <tree-ish>::
514         Indicates a tree, commit or tag object name.  A
515         command that takes a <tree-ish> argument ultimately wants to
516         operate on a <tree> object but automatically dereferences
517         <commit> and <tag> objects that point at a <tree>.
518
519 <type>::
520         Indicates that an object type is required.
521         Currently one of: `blob`, `tree`, `commit`, or `tag`.
522
523 <file>::
524         Indicates a filename - almost always relative to the
525         root of the tree structure `GIT_INDEX_FILE` describes.
526
527 Symbolic Identifiers
528 --------------------
529 Any git command accepting any <object> can also use the following
530 symbolic notation:
531
532 HEAD::
533         indicates the head of the current branch (i.e. the
534         contents of `$GIT_DIR/HEAD`).
535
536 <tag>::
537         a valid tag 'name'
538         (i.e. the contents of `$GIT_DIR/refs/tags/<tag>`).
539
540 <head>::
541         a valid head 'name'
542         (i.e. the contents of `$GIT_DIR/refs/heads/<head>`).
543
544
545 File/Directory Structure
546 ------------------------
547
548 Please see link:repository-layout.html[repository layout] document.
549
550 Read link:hooks.html[hooks] for more details about each hook.
551
552 Higher level SCMs may provide and manage additional information in the
553 `$GIT_DIR`.
554
555
556 Terminology
557 -----------
558 Please see link:glossary.html[glossary] document.
559
560
561 Environment Variables
562 ---------------------
563 Various git commands use the following environment variables:
564
565 The git Repository
566 ~~~~~~~~~~~~~~~~~~
567 These environment variables apply to 'all' core git commands. Nb: it
568 is worth noting that they may be used/overridden by SCMS sitting above
569 git so take care if using Cogito etc.
570
571 'GIT_INDEX_FILE'::
572         This environment allows the specification of an alternate
573         index file. If not specified, the default of `$GIT_DIR/index`
574         is used.
575
576 'GIT_OBJECT_DIRECTORY'::
577         If the object storage directory is specified via this
578         environment variable then the sha1 directories are created
579         underneath - otherwise the default `$GIT_DIR/objects`
580         directory is used.
581
582 'GIT_ALTERNATE_OBJECT_DIRECTORIES'::
583         Due to the immutable nature of git objects, old objects can be
584         archived into shared, read-only directories. This variable
585         specifies a ":" separated list of git object directories which
586         can be used to search for git objects. New objects will not be
587         written to these directories.
588
589 'GIT_DIR'::
590         If the 'GIT_DIR' environment variable is set then it
591         specifies a path to use instead of the default `.git`
592         for the base of the repository.
593
594 git Commits
595 ~~~~~~~~~~~
596 'GIT_AUTHOR_NAME'::
597 'GIT_AUTHOR_EMAIL'::
598 'GIT_AUTHOR_DATE'::
599 'GIT_COMMITTER_NAME'::
600 'GIT_COMMITTER_EMAIL'::
601         see gitlink:git-commit-tree[1]
602
603 git Diffs
604 ~~~~~~~~~
605 'GIT_DIFF_OPTS'::
606 'GIT_EXTERNAL_DIFF'::
607         see the "generating patches" section in :
608         gitlink:git-diff-index[1];
609         gitlink:git-diff-files[1];
610         gitlink:git-diff-tree[1]
611
612 Discussion[[Discussion]]
613 ------------------------
614 include::README[]
615
616 Authors
617 -------
618 * git's founding father is Linus Torvalds <torvalds@osdl.org>.
619 * The current git nurse is Junio C Hamano <junkio@cox.net>.
620 * The git potty was written by Andres Ericsson <ae@op5.se>.
621 * General upbringing is handled by the git-list <git@vger.kernel.org>.
622
623 Documentation
624 --------------
625 The documentation for git suite was started by David Greaves
626 <david@dgreaves.com>, and later enhanced greatly by the
627 contributors on the git-list <git@vger.kernel.org>.
628
629 GIT
630 ---
631 Part of the gitlink:git[7] suite
632