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