4facf2309512380fc796e5f64e400c6ebcb08dbd
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-relink[1]::
228 Hardlink common objects in local repositories.
230 gitlink:git-svn[1]::
231 Bidirectional operation between a single Subversion branch and git.
233 gitlink:git-svnimport[1]::
234 Import a SVN repository into git.
236 gitlink:git-sh-setup[1]::
237 Common git shell script setup code.
239 gitlink:git-symbolic-ref[1]::
240 Read and modify symbolic refs.
242 gitlink:git-tag[1]::
243 An example script to create a tag object signed with GPG.
245 gitlink:git-update-ref[1]::
246 Update the object name stored in a ref safely.
249 Interrogators:
251 gitlink:git-annotate[1]::
252 Annotate file lines with commit info.
254 gitlink:git-blame[1]::
255 Blame file lines on commits.
257 gitlink:git-pickaxe[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-send-email[1]::
309 Send patch e-mails out of "format-patch --mbox" output.
311 gitlink:git-symbolic-ref[1]::
312 Read and modify symbolic refs.
314 gitlink:git-stripspace[1]::
315 Filter out empty lines.
318 Low-level commands (plumbing)
319 -----------------------------
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].
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.
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.
338 gitlink:git-checkout-index[1]::
339 Copy files from the index to the working tree.
341 gitlink:git-commit-tree[1]::
342 Creates a new commit object.
344 gitlink:git-hash-object[1]::
345 Computes the object ID from a file.
347 gitlink:git-index-pack[1]::
348 Build pack idx file for an existing packed archive.
350 gitlink:git-init-db[1]::
351 Creates an empty git object database, or reinitialize an
352 existing one.
354 gitlink:git-merge-index[1]::
355 Runs a merge for files needing merging.
357 gitlink:git-mktag[1]::
358 Creates a tag object.
360 gitlink:git-mktree[1]::
361 Build a tree-object from ls-tree formatted text.
363 gitlink:git-pack-objects[1]::
364 Creates a packed archive of objects.
366 gitlink:git-prune-packed[1]::
367 Remove extra objects that are already in pack files.
369 gitlink:git-read-tree[1]::
370 Reads tree information into the index.
372 gitlink:git-repo-config[1]::
373 Get and set options in .git/config.
375 gitlink:git-unpack-objects[1]::
376 Unpacks objects out of a packed archive.
378 gitlink:git-update-index[1]::
379 Registers files in the working tree to the index.
381 gitlink:git-write-tree[1]::
382 Creates a tree from the index.
385 Interrogation commands
386 ~~~~~~~~~~~~~~~~~~~~~~
388 gitlink:git-cat-file[1]::
389 Provide content or type/size information for repository objects.
391 gitlink:git-describe[1]::
392 Show the most recent tag that is reachable from a commit.
394 gitlink:git-diff-index[1]::
395 Compares content and mode of blobs between the index and repository.
397 gitlink:git-diff-files[1]::
398 Compares files in the working tree and the index.
400 gitlink:git-diff-stages[1]::
401 Compares two "merge stages" in the index.
403 gitlink:git-diff-tree[1]::
404 Compares the content and mode of blobs found via two tree objects.
406 gitlink:git-for-each-ref[1]::
407 Output information on each ref.
409 gitlink:git-fsck-objects[1]::
410 Verifies the connectivity and validity of the objects in the database.
412 gitlink:git-ls-files[1]::
413 Information about files in the index and the working tree.
415 gitlink:git-ls-tree[1]::
416 Displays a tree object in human readable form.
418 gitlink:git-merge-base[1]::
419 Finds as good common ancestors as possible for a merge.
421 gitlink:git-name-rev[1]::
422 Find symbolic names for given revs.
424 gitlink:git-pack-redundant[1]::
425 Find redundant pack files.
427 gitlink:git-rev-list[1]::
428 Lists commit objects in reverse chronological order.
430 gitlink:git-show-index[1]::
431 Displays contents of a pack idx file.
433 gitlink:git-show-ref[1]::
434 List references in a local repository.
436 gitlink:git-tar-tree[1]::
437 Creates a tar archive of the files in the named tree object.
439 gitlink:git-unpack-file[1]::
440 Creates a temporary file with a blob's contents.
442 gitlink:git-var[1]::
443 Displays a git logical variable.
445 gitlink:git-verify-pack[1]::
446 Validates packed git archive files.
448 In general, the interrogate commands do not touch the files in
449 the working tree.
452 Synching repositories
453 ~~~~~~~~~~~~~~~~~~~~~
455 gitlink:git-fetch-pack[1]::
456 Updates from a remote repository (engine for ssh and
457 local transport).
459 gitlink:git-http-fetch[1]::
460 Downloads a remote git repository via HTTP by walking
461 commit chain.
463 gitlink:git-local-fetch[1]::
464 Duplicates another git repository on a local system by
465 walking commit chain.
467 gitlink:git-peek-remote[1]::
468 Lists references on a remote repository using
469 upload-pack protocol (engine for ssh and local
470 transport).
472 gitlink:git-receive-pack[1]::
473 Invoked by 'git-send-pack' to receive what is pushed to it.
475 gitlink:git-send-pack[1]::
476 Pushes to a remote repository, intelligently.
478 gitlink:git-http-push[1]::
479 Push missing objects using HTTP/DAV.
481 gitlink:git-shell[1]::
482 Restricted shell for GIT-only SSH access.
484 gitlink:git-ssh-fetch[1]::
485 Pulls from a remote repository over ssh connection by
486 walking commit chain.
488 gitlink:git-ssh-upload[1]::
489 Helper "server-side" program used by git-ssh-fetch.
491 gitlink:git-update-server-info[1]::
492 Updates auxiliary information on a dumb server to help
493 clients discover references and packs on it.
495 gitlink:git-upload-archive[1]::
496 Invoked by 'git-archive' to send a generated archive.
498 gitlink:git-upload-pack[1]::
499 Invoked by 'git-fetch-pack' to push
500 what are asked for.
503 Configuration Mechanism
504 -----------------------
506 Starting from 0.99.9 (actually mid 0.99.8.GIT), `.git/config` file
507 is used to hold per-repository configuration options. It is a
508 simple text file modeled after `.ini` format familiar to some
509 people. Here is an example:
511 ------------
512 #
513 # A '#' or ';' character indicates a comment.
514 #
516 ; core variables
517 [core]
518 ; Don't trust file modes
519 filemode = false
521 ; user identity
522 [user]
523 name = "Junio C Hamano"
524 email = "junkio@twinsun.com"
526 ------------
528 Various commands read from the configuration file and adjust
529 their operation accordingly.
532 Identifier Terminology
533 ----------------------
534 <object>::
535 Indicates the object name for any type of object.
537 <blob>::
538 Indicates a blob object name.
540 <tree>::
541 Indicates a tree object name.
543 <commit>::
544 Indicates a commit object name.
546 <tree-ish>::
547 Indicates a tree, commit or tag object name. A
548 command that takes a <tree-ish> argument ultimately wants to
549 operate on a <tree> object but automatically dereferences
550 <commit> and <tag> objects that point at a <tree>.
552 <type>::
553 Indicates that an object type is required.
554 Currently one of: `blob`, `tree`, `commit`, or `tag`.
556 <file>::
557 Indicates a filename - almost always relative to the
558 root of the tree structure `GIT_INDEX_FILE` describes.
560 Symbolic Identifiers
561 --------------------
562 Any git command accepting any <object> can also use the following
563 symbolic notation:
565 HEAD::
566 indicates the head of the current branch (i.e. the
567 contents of `$GIT_DIR/HEAD`).
569 <tag>::
570 a valid tag 'name'
571 (i.e. the contents of `$GIT_DIR/refs/tags/<tag>`).
573 <head>::
574 a valid head 'name'
575 (i.e. the contents of `$GIT_DIR/refs/heads/<head>`).
577 For a more complete list of ways to spell object names, see
578 "SPECIFYING REVISIONS" section in gitlink:git-rev-parse[1].
581 File/Directory Structure
582 ------------------------
584 Please see link:repository-layout.html[repository layout] document.
586 Read link:hooks.html[hooks] for more details about each hook.
588 Higher level SCMs may provide and manage additional information in the
589 `$GIT_DIR`.
592 Terminology
593 -----------
594 Please see link:glossary.html[glossary] document.
597 Environment Variables
598 ---------------------
599 Various git commands use the following environment variables:
601 The git Repository
602 ~~~~~~~~~~~~~~~~~~
603 These environment variables apply to 'all' core git commands. Nb: it
604 is worth noting that they may be used/overridden by SCMS sitting above
605 git so take care if using Cogito etc.
607 'GIT_INDEX_FILE'::
608 This environment allows the specification of an alternate
609 index file. If not specified, the default of `$GIT_DIR/index`
610 is used.
612 'GIT_OBJECT_DIRECTORY'::
613 If the object storage directory is specified via this
614 environment variable then the sha1 directories are created
615 underneath - otherwise the default `$GIT_DIR/objects`
616 directory is used.
618 'GIT_ALTERNATE_OBJECT_DIRECTORIES'::
619 Due to the immutable nature of git objects, old objects can be
620 archived into shared, read-only directories. This variable
621 specifies a ":" separated list of git object directories which
622 can be used to search for git objects. New objects will not be
623 written to these directories.
625 'GIT_DIR'::
626 If the 'GIT_DIR' environment variable is set then it
627 specifies a path to use instead of the default `.git`
628 for the base of the repository.
630 git Commits
631 ~~~~~~~~~~~
632 'GIT_AUTHOR_NAME'::
633 'GIT_AUTHOR_EMAIL'::
634 'GIT_AUTHOR_DATE'::
635 'GIT_COMMITTER_NAME'::
636 'GIT_COMMITTER_EMAIL'::
637 see gitlink:git-commit-tree[1]
639 git Diffs
640 ~~~~~~~~~
641 'GIT_DIFF_OPTS'::
642 'GIT_EXTERNAL_DIFF'::
643 see the "generating patches" section in :
644 gitlink:git-diff-index[1];
645 gitlink:git-diff-files[1];
646 gitlink:git-diff-tree[1]
648 other
649 ~~~~~
650 'GIT_PAGER'::
651 This environment variable overrides `$PAGER`.
653 'GIT_TRACE'::
654 If this variable is set to "1", "2" or "true" (comparison
655 is case insensitive), git will print `trace:` messages on
656 stderr telling about alias expansion, built-in command
657 execution and external command execution.
658 If this variable is set to an integer value greater than 1
659 and lower than 10 (strictly) then git will interpret this
660 value as an open file descriptor and will try to write the
661 trace messages into this file descriptor.
662 Alternatively, if this variable is set to an absolute path
663 (starting with a '/' character), git will interpret this
664 as a file path and will try to write the trace messages
665 into it.
667 Discussion[[Discussion]]
668 ------------------------
669 include::README[]
671 Authors
672 -------
673 * git's founding father is Linus Torvalds <torvalds@osdl.org>.
674 * The current git nurse is Junio C Hamano <junkio@cox.net>.
675 * The git potty was written by Andres Ericsson <ae@op5.se>.
676 * General upbringing is handled by the git-list <git@vger.kernel.org>.
678 Documentation
679 --------------
680 The documentation for git suite was started by David Greaves
681 <david@dgreaves.com>, and later enhanced greatly by the
682 contributors on the git-list <git@vger.kernel.org>.
684 GIT
685 ---
686 Part of the gitlink:git[7] suite