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