4ed3eed13d383cac4f1fa171b3ab6fb62f63c06a
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-lost-found[1]::
216 Recover lost refs that luckily have not yet been pruned.
218 gitlink:git-merge-one-file[1]::
219 The standard helper program to use with `git-merge-index`.
221 gitlink:git-prune[1]::
222 Prunes all unreachable objects from the object database.
224 gitlink:git-quiltimport[1]::
225 Applies a quilt patchset onto the current branch.
227 gitlink:git-reflog[1]::
228 Manage reflog information.
230 gitlink:git-relink[1]::
231 Hardlink common objects in local repositories.
233 gitlink:git-svn[1]::
234 Bidirectional operation between a single Subversion branch and git.
236 gitlink:git-svnimport[1]::
237 Import a SVN repository into git.
239 gitlink:git-sh-setup[1]::
240 Common git shell script setup code.
242 gitlink:git-symbolic-ref[1]::
243 Read and modify symbolic refs.
245 gitlink:git-tag[1]::
246 An example script to create a tag object signed with GPG.
248 gitlink:git-update-ref[1]::
249 Update the object name stored in a ref safely.
252 Interrogators:
254 gitlink:git-annotate[1]::
255 Annotate file lines with commit info.
257 gitlink:git-blame[1]::
258 Find out where each line in a file came from.
260 gitlink:git-check-ref-format[1]::
261 Make sure ref name is well formed.
263 gitlink:git-cherry[1]::
264 Find commits not merged upstream.
266 gitlink:git-count-objects[1]::
267 Count unpacked number of objects and their disk consumption.
269 gitlink:git-daemon[1]::
270 A really simple server for git repositories.
272 gitlink:git-fmt-merge-msg[1]::
273 Produce a merge commit message.
275 gitlink:git-get-tar-commit-id[1]::
276 Extract commit ID from an archive created using git-tar-tree.
278 gitlink:git-imap-send[1]::
279 Dump a mailbox from stdin into an imap folder.
281 gitlink:git-instaweb[1]::
282 Instantly browse your working repository in gitweb.
284 gitlink:git-mailinfo[1]::
285 Extracts patch and authorship information from a single
286 e-mail message, optionally transliterating the commit
287 message into utf-8.
289 gitlink:git-mailsplit[1]::
290 A stupid program to split UNIX mbox format mailbox into
291 individual pieces of e-mail.
293 gitlink:git-merge-tree[1]::
294 Show three-way merge without touching index.
296 gitlink:git-patch-id[1]::
297 Compute unique ID for a patch.
299 gitlink:git-parse-remote[1]::
300 Routines to help parsing `$GIT_DIR/remotes/` files.
302 gitlink:git-request-pull[1]::
303 git-request-pull.
305 gitlink:git-rev-parse[1]::
306 Pick out and massage parameters.
308 gitlink:git-runstatus[1]::
309 A helper for git-status and git-commit.
311 gitlink:git-send-email[1]::
312 Send patch e-mails out of "format-patch --mbox" output.
314 gitlink:git-symbolic-ref[1]::
315 Read and modify symbolic refs.
317 gitlink:git-stripspace[1]::
318 Filter out empty lines.
321 Low-level commands (plumbing)
322 -----------------------------
324 Although git includes its
325 own porcelain layer, its low-level commands are sufficient to support
326 development of alternative porcelains. Developers of such porcelains
327 might start by reading about gitlink:git-update-index[1] and
328 gitlink:git-read-tree[1].
330 We divide the low-level commands into commands that manipulate objects (in
331 the repository, index, and working tree), commands that interrogate and
332 compare objects, and commands that move objects and references between
333 repositories.
335 Manipulation commands
336 ~~~~~~~~~~~~~~~~~~~~~
337 gitlink:git-apply[1]::
338 Reads a "diff -up1" or git generated patch file and
339 applies it to the working tree.
341 gitlink:git-checkout-index[1]::
342 Copy files from the index to the working tree.
344 gitlink:git-commit-tree[1]::
345 Creates a new commit object.
347 gitlink:git-hash-object[1]::
348 Computes the object ID from a file.
350 gitlink:git-index-pack[1]::
351 Build pack idx file for an existing packed archive.
353 gitlink:git-init-db[1]::
354 Creates an empty git object database, or reinitialize an
355 existing one.
357 gitlink:git-merge-file[1]::
358 Runs a threeway merge.
360 gitlink:git-merge-index[1]::
361 Runs a merge for files needing merging.
363 gitlink:git-mktag[1]::
364 Creates a tag object.
366 gitlink:git-mktree[1]::
367 Build a tree-object from ls-tree formatted text.
369 gitlink:git-pack-objects[1]::
370 Creates a packed archive of objects.
372 gitlink:git-prune-packed[1]::
373 Remove extra objects that are already in pack files.
375 gitlink:git-read-tree[1]::
376 Reads tree information into the index.
378 gitlink:git-repo-config[1]::
379 Get and set options in .git/config.
381 gitlink:git-unpack-objects[1]::
382 Unpacks objects out of a packed archive.
384 gitlink:git-update-index[1]::
385 Registers files in the working tree to the index.
387 gitlink:git-write-tree[1]::
388 Creates a tree from the index.
391 Interrogation commands
392 ~~~~~~~~~~~~~~~~~~~~~~
394 gitlink:git-cat-file[1]::
395 Provide content or type/size information for repository objects.
397 gitlink:git-describe[1]::
398 Show the most recent tag that is reachable from a commit.
400 gitlink:git-diff-index[1]::
401 Compares content and mode of blobs between the index and repository.
403 gitlink:git-diff-files[1]::
404 Compares files in the working tree and the index.
406 gitlink:git-diff-stages[1]::
407 Compares two "merge stages" in the index.
409 gitlink:git-diff-tree[1]::
410 Compares the content and mode of blobs found via two tree objects.
412 gitlink:git-for-each-ref[1]::
413 Output information on each ref.
415 gitlink:git-fsck-objects[1]::
416 Verifies the connectivity and validity of the objects in the database.
418 gitlink:git-ls-files[1]::
419 Information about files in the index and the working tree.
421 gitlink:git-ls-tree[1]::
422 Displays a tree object in human readable form.
424 gitlink:git-merge-base[1]::
425 Finds as good common ancestors as possible for a merge.
427 gitlink:git-name-rev[1]::
428 Find symbolic names for given revs.
430 gitlink:git-pack-redundant[1]::
431 Find redundant pack files.
433 gitlink:git-rev-list[1]::
434 Lists commit objects in reverse chronological order.
436 gitlink:git-show-index[1]::
437 Displays contents of a pack idx file.
439 gitlink:git-show-ref[1]::
440 List references in a local repository.
442 gitlink:git-tar-tree[1]::
443 Creates a tar archive of the files in the named tree object.
445 gitlink:git-unpack-file[1]::
446 Creates a temporary file with a blob's contents.
448 gitlink:git-var[1]::
449 Displays a git logical variable.
451 gitlink:git-verify-pack[1]::
452 Validates packed git archive files.
454 In general, the interrogate commands do not touch the files in
455 the working tree.
458 Synching repositories
459 ~~~~~~~~~~~~~~~~~~~~~
461 gitlink:git-fetch-pack[1]::
462 Updates from a remote repository (engine for ssh and
463 local transport).
465 gitlink:git-http-fetch[1]::
466 Downloads a remote git repository via HTTP by walking
467 commit chain.
469 gitlink:git-local-fetch[1]::
470 Duplicates another git repository on a local system by
471 walking commit chain.
473 gitlink:git-peek-remote[1]::
474 Lists references on a remote repository using
475 upload-pack protocol (engine for ssh and local
476 transport).
478 gitlink:git-receive-pack[1]::
479 Invoked by 'git-send-pack' to receive what is pushed to it.
481 gitlink:git-send-pack[1]::
482 Pushes to a remote repository, intelligently.
484 gitlink:git-http-push[1]::
485 Push missing objects using HTTP/DAV.
487 gitlink:git-shell[1]::
488 Restricted shell for GIT-only SSH access.
490 gitlink:git-ssh-fetch[1]::
491 Pulls from a remote repository over ssh connection by
492 walking commit chain.
494 gitlink:git-ssh-upload[1]::
495 Helper "server-side" program used by git-ssh-fetch.
497 gitlink:git-update-server-info[1]::
498 Updates auxiliary information on a dumb server to help
499 clients discover references and packs on it.
501 gitlink:git-upload-archive[1]::
502 Invoked by 'git-archive' to send a generated archive.
504 gitlink:git-upload-pack[1]::
505 Invoked by 'git-fetch-pack' to push
506 what are asked for.
509 Configuration Mechanism
510 -----------------------
512 Starting from 0.99.9 (actually mid 0.99.8.GIT), `.git/config` file
513 is used to hold per-repository configuration options. It is a
514 simple text file modeled after `.ini` format familiar to some
515 people. Here is an example:
517 ------------
518 #
519 # A '#' or ';' character indicates a comment.
520 #
522 ; core variables
523 [core]
524 ; Don't trust file modes
525 filemode = false
527 ; user identity
528 [user]
529 name = "Junio C Hamano"
530 email = "junkio@twinsun.com"
532 ------------
534 Various commands read from the configuration file and adjust
535 their operation accordingly.
538 Identifier Terminology
539 ----------------------
540 <object>::
541 Indicates the object name for any type of object.
543 <blob>::
544 Indicates a blob object name.
546 <tree>::
547 Indicates a tree object name.
549 <commit>::
550 Indicates a commit object name.
552 <tree-ish>::
553 Indicates a tree, commit or tag object name. A
554 command that takes a <tree-ish> argument ultimately wants to
555 operate on a <tree> object but automatically dereferences
556 <commit> and <tag> objects that point at a <tree>.
558 <type>::
559 Indicates that an object type is required.
560 Currently one of: `blob`, `tree`, `commit`, or `tag`.
562 <file>::
563 Indicates a filename - almost always relative to the
564 root of the tree structure `GIT_INDEX_FILE` describes.
566 Symbolic Identifiers
567 --------------------
568 Any git command accepting any <object> can also use the following
569 symbolic notation:
571 HEAD::
572 indicates the head of the current branch (i.e. the
573 contents of `$GIT_DIR/HEAD`).
575 <tag>::
576 a valid tag 'name'
577 (i.e. the contents of `$GIT_DIR/refs/tags/<tag>`).
579 <head>::
580 a valid head 'name'
581 (i.e. the contents of `$GIT_DIR/refs/heads/<head>`).
583 For a more complete list of ways to spell object names, see
584 "SPECIFYING REVISIONS" section in gitlink:git-rev-parse[1].
587 File/Directory Structure
588 ------------------------
590 Please see link:repository-layout.html[repository layout] document.
592 Read link:hooks.html[hooks] for more details about each hook.
594 Higher level SCMs may provide and manage additional information in the
595 `$GIT_DIR`.
598 Terminology
599 -----------
600 Please see link:glossary.html[glossary] document.
603 Environment Variables
604 ---------------------
605 Various git commands use the following environment variables:
607 The git Repository
608 ~~~~~~~~~~~~~~~~~~
609 These environment variables apply to 'all' core git commands. Nb: it
610 is worth noting that they may be used/overridden by SCMS sitting above
611 git so take care if using Cogito etc.
613 'GIT_INDEX_FILE'::
614 This environment allows the specification of an alternate
615 index file. If not specified, the default of `$GIT_DIR/index`
616 is used.
618 'GIT_OBJECT_DIRECTORY'::
619 If the object storage directory is specified via this
620 environment variable then the sha1 directories are created
621 underneath - otherwise the default `$GIT_DIR/objects`
622 directory is used.
624 'GIT_ALTERNATE_OBJECT_DIRECTORIES'::
625 Due to the immutable nature of git objects, old objects can be
626 archived into shared, read-only directories. This variable
627 specifies a ":" separated list of git object directories which
628 can be used to search for git objects. New objects will not be
629 written to these directories.
631 'GIT_DIR'::
632 If the 'GIT_DIR' environment variable is set then it
633 specifies a path to use instead of the default `.git`
634 for the base of the repository.
636 git Commits
637 ~~~~~~~~~~~
638 'GIT_AUTHOR_NAME'::
639 'GIT_AUTHOR_EMAIL'::
640 'GIT_AUTHOR_DATE'::
641 'GIT_COMMITTER_NAME'::
642 'GIT_COMMITTER_EMAIL'::
643 see gitlink:git-commit-tree[1]
645 git Diffs
646 ~~~~~~~~~
647 'GIT_DIFF_OPTS'::
648 Only valid setting is "--unified=??" or "-u??" to set the
649 number of context lines shown when a unified diff is created.
650 This takes precedence over any "-U" or "--unified" option
651 value passed on the git diff command line.
653 'GIT_EXTERNAL_DIFF'::
654 When the environment variable 'GIT_EXTERNAL_DIFF' is set, the
655 program named by it is called, instead of the diff invocation
656 described above. For a path that is added, removed, or modified,
657 'GIT_EXTERNAL_DIFF' is called with 7 parameters:
659 path old-file old-hex old-mode new-file new-hex new-mode
660 +
661 where:
663 <old|new>-file:: are files GIT_EXTERNAL_DIFF can use to read the
664 contents of <old|new>,
665 <old|new>-hex:: are the 40-hexdigit SHA1 hashes,
666 <old|new>-mode:: are the octal representation of the file modes.
668 +
669 The file parameters can point at the user's working file
670 (e.g. `new-file` in "git-diff-files"), `/dev/null` (e.g. `old-file`
671 when a new file is added), or a temporary file (e.g. `old-file` in the
672 index). 'GIT_EXTERNAL_DIFF' should not worry about unlinking the
673 temporary file --- it is removed when 'GIT_EXTERNAL_DIFF' exits.
674 +
675 For a path that is unmerged, 'GIT_EXTERNAL_DIFF' is called with 1
676 parameter, <path>.
678 other
679 ~~~~~
680 'GIT_PAGER'::
681 This environment variable overrides `$PAGER`.
683 'GIT_TRACE'::
684 If this variable is set to "1", "2" or "true" (comparison
685 is case insensitive), git will print `trace:` messages on
686 stderr telling about alias expansion, built-in command
687 execution and external command execution.
688 If this variable is set to an integer value greater than 1
689 and lower than 10 (strictly) then git will interpret this
690 value as an open file descriptor and will try to write the
691 trace messages into this file descriptor.
692 Alternatively, if this variable is set to an absolute path
693 (starting with a '/' character), git will interpret this
694 as a file path and will try to write the trace messages
695 into it.
697 Discussion[[Discussion]]
698 ------------------------
699 include::README[]
701 Authors
702 -------
703 * git's founding father is Linus Torvalds <torvalds@osdl.org>.
704 * The current git nurse is Junio C Hamano <junkio@cox.net>.
705 * The git potty was written by Andres Ericsson <ae@op5.se>.
706 * General upbringing is handled by the git-list <git@vger.kernel.org>.
708 Documentation
709 --------------
710 The documentation for git suite was started by David Greaves
711 <david@dgreaves.com>, and later enhanced greatly by the
712 contributors on the git-list <git@vger.kernel.org>.
714 GIT
715 ---
716 Part of the gitlink:git[7] suite