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