0679e3c209278d07173007e514c09e78fe9a4e49
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-pull[1]::
145 Fetch from and merge with a remote repository or a local branch.
147 gitlink:git-push[1]::
148 Update remote refs along with associated objects.
150 gitlink:git-rebase[1]::
151 Rebase local commits to the updated upstream head.
153 gitlink:git-repack[1]::
154 Pack unpacked objects in a repository.
156 gitlink:git-rerere[1]::
157 Reuse recorded resolution of conflicted merges.
159 gitlink:git-reset[1]::
160 Reset current HEAD to the specified state.
162 gitlink:git-resolve[1]::
163 Merge two commits.
165 gitlink:git-revert[1]::
166 Revert an existing commit.
168 gitlink:git-rm[1]::
169 Remove files from the working tree and from the index.
171 gitlink:git-shortlog[1]::
172 Summarizes 'git log' output.
174 gitlink:git-show[1]::
175 Show one commit log and its diff.
177 gitlink:git-show-branch[1]::
178 Show branches and their commits.
180 gitlink:git-status[1]::
181 Shows the working tree status.
183 gitlink:git-verify-tag[1]::
184 Check the GPG signature of tag.
186 gitlink:git-whatchanged[1]::
187 Shows commit logs and differences they introduce.
190 Ancillary Commands
191 ~~~~~~~~~~~~~~~~~~
192 Manipulators:
194 gitlink:git-applypatch[1]::
195 Apply one patch extracted from an e-mail.
197 gitlink:git-archimport[1]::
198 Import an arch repository into git.
200 gitlink:git-convert-objects[1]::
201 Converts old-style git repository.
203 gitlink:git-cvsimport[1]::
204 Salvage your data out of another SCM people love to hate.
206 gitlink:git-cvsexportcommit[1]::
207 Export a single commit to a CVS checkout.
209 gitlink:git-cvsserver[1]::
210 A CVS server emulator for git.
212 gitlink:git-lost-found[1]::
213 Recover lost refs that luckily have not yet been pruned.
215 gitlink:git-merge-one-file[1]::
216 The standard helper program to use with `git-merge-index`.
218 gitlink:git-prune[1]::
219 Prunes all unreachable objects from the object database.
221 gitlink:git-quiltimport[1]::
222 Applies a quilt patchset onto the current branch.
224 gitlink:git-relink[1]::
225 Hardlink common objects in local repositories.
227 gitlink:git-svn[1]::
228 Bidirectional operation between a single Subversion branch and git.
230 gitlink:git-svnimport[1]::
231 Import a SVN repository into git.
233 gitlink:git-sh-setup[1]::
234 Common git shell script setup code.
236 gitlink:git-symbolic-ref[1]::
237 Read and modify symbolic refs.
239 gitlink:git-tag[1]::
240 An example script to create a tag object signed with GPG.
242 gitlink:git-update-ref[1]::
243 Update the object name stored in a ref safely.
246 Interrogators:
248 gitlink:git-annotate[1]::
249 Annotate file lines with commit info.
251 gitlink:git-blame[1]::
252 Blame file lines on commits.
254 gitlink:git-check-ref-format[1]::
255 Make sure ref name is well formed.
257 gitlink:git-cherry[1]::
258 Find commits not merged upstream.
260 gitlink:git-count-objects[1]::
261 Count unpacked number of objects and their disk consumption.
263 gitlink:git-daemon[1]::
264 A really simple server for git repositories.
266 gitlink:git-fmt-merge-msg[1]::
267 Produce a merge commit message.
269 gitlink:git-get-tar-commit-id[1]::
270 Extract commit ID from an archive created using git-tar-tree.
272 gitlink:git-imap-send[1]::
273 Dump a mailbox from stdin into an imap folder.
275 gitlink:git-instaweb[1]::
276 Instantly browse your working repository in gitweb.
278 gitlink:git-mailinfo[1]::
279 Extracts patch and authorship information from a single
280 e-mail message, optionally transliterating the commit
281 message into utf-8.
283 gitlink:git-mailsplit[1]::
284 A stupid program to split UNIX mbox format mailbox into
285 individual pieces of e-mail.
287 gitlink:git-merge-tree[1]::
288 Show three-way merge without touching index.
290 gitlink:git-patch-id[1]::
291 Compute unique ID for a patch.
293 gitlink:git-parse-remote[1]::
294 Routines to help parsing `$GIT_DIR/remotes/` files.
296 gitlink:git-request-pull[1]::
297 git-request-pull.
299 gitlink:git-rev-parse[1]::
300 Pick out and massage parameters.
302 gitlink:git-send-email[1]::
303 Send patch e-mails out of "format-patch --mbox" output.
305 gitlink:git-symbolic-ref[1]::
306 Read and modify symbolic refs.
308 gitlink:git-stripspace[1]::
309 Filter out empty lines.
312 Low-level commands (plumbing)
313 -----------------------------
315 Although git includes its
316 own porcelain layer, its low-level commands are sufficient to support
317 development of alternative porcelains. Developers of such porcelains
318 might start by reading about gitlink:git-update-index[1] and
319 gitlink:git-read-tree[1].
321 We divide the low-level commands into commands that manipulate objects (in
322 the repository, index, and working tree), commands that interrogate and
323 compare objects, and commands that move objects and references between
324 repositories.
326 Manipulation commands
327 ~~~~~~~~~~~~~~~~~~~~~
328 gitlink:git-apply[1]::
329 Reads a "diff -up1" or git generated patch file and
330 applies it to the working tree.
332 gitlink:git-checkout-index[1]::
333 Copy files from the index to the working tree.
335 gitlink:git-commit-tree[1]::
336 Creates a new commit object.
338 gitlink:git-hash-object[1]::
339 Computes the object ID from a file.
341 gitlink:git-index-pack[1]::
342 Build pack idx file for an existing packed archive.
344 gitlink:git-init-db[1]::
345 Creates an empty git object database, or reinitialize an
346 existing one.
348 gitlink:git-merge-index[1]::
349 Runs a merge for files needing merging.
351 gitlink:git-mktag[1]::
352 Creates a tag object.
354 gitlink:git-mktree[1]::
355 Build a tree-object from ls-tree formatted text.
357 gitlink:git-pack-objects[1]::
358 Creates a packed archive of objects.
360 gitlink:git-prune-packed[1]::
361 Remove extra objects that are already in pack files.
363 gitlink:git-read-tree[1]::
364 Reads tree information into the index.
366 gitlink:git-repo-config[1]::
367 Get and set options in .git/config.
369 gitlink:git-unpack-objects[1]::
370 Unpacks objects out of a packed archive.
372 gitlink:git-update-index[1]::
373 Registers files in the working tree to the index.
375 gitlink:git-write-tree[1]::
376 Creates a tree from the index.
379 Interrogation commands
380 ~~~~~~~~~~~~~~~~~~~~~~
382 gitlink:git-cat-file[1]::
383 Provide content or type/size information for repository objects.
385 gitlink:git-describe[1]::
386 Show the most recent tag that is reachable from a commit.
388 gitlink:git-diff-index[1]::
389 Compares content and mode of blobs between the index and repository.
391 gitlink:git-diff-files[1]::
392 Compares files in the working tree and the index.
394 gitlink:git-diff-stages[1]::
395 Compares two "merge stages" in the index.
397 gitlink:git-diff-tree[1]::
398 Compares the content and mode of blobs found via two tree objects.
400 gitlink:git-for-each-ref[1]::
401 Output information on each ref.
403 gitlink:git-fsck-objects[1]::
404 Verifies the connectivity and validity of the objects in the database.
406 gitlink:git-ls-files[1]::
407 Information about files in the index and the working tree.
409 gitlink:git-ls-tree[1]::
410 Displays a tree object in human readable form.
412 gitlink:git-merge-base[1]::
413 Finds as good common ancestors as possible for a merge.
415 gitlink:git-name-rev[1]::
416 Find symbolic names for given revs.
418 gitlink:git-pack-redundant[1]::
419 Find redundant pack files.
421 gitlink:git-rev-list[1]::
422 Lists commit objects in reverse chronological order.
424 gitlink:git-show-index[1]::
425 Displays contents of a pack idx file.
427 gitlink:git-tar-tree[1]::
428 Creates a tar archive of the files in the named tree object.
430 gitlink:git-unpack-file[1]::
431 Creates a temporary file with a blob's contents.
433 gitlink:git-var[1]::
434 Displays a git logical variable.
436 gitlink:git-verify-pack[1]::
437 Validates packed git archive files.
439 In general, the interrogate commands do not touch the files in
440 the working tree.
443 Synching repositories
444 ~~~~~~~~~~~~~~~~~~~~~
446 gitlink:git-fetch-pack[1]::
447 Updates from a remote repository (engine for ssh and
448 local transport).
450 gitlink:git-http-fetch[1]::
451 Downloads a remote git repository via HTTP by walking
452 commit chain.
454 gitlink:git-local-fetch[1]::
455 Duplicates another git repository on a local system by
456 walking commit chain.
458 gitlink:git-peek-remote[1]::
459 Lists references on a remote repository using
460 upload-pack protocol (engine for ssh and local
461 transport).
463 gitlink:git-receive-pack[1]::
464 Invoked by 'git-send-pack' to receive what is pushed to it.
466 gitlink:git-send-pack[1]::
467 Pushes to a remote repository, intelligently.
469 gitlink:git-http-push[1]::
470 Push missing objects using HTTP/DAV.
472 gitlink:git-shell[1]::
473 Restricted shell for GIT-only SSH access.
475 gitlink:git-ssh-fetch[1]::
476 Pulls from a remote repository over ssh connection by
477 walking commit chain.
479 gitlink:git-ssh-upload[1]::
480 Helper "server-side" program used by git-ssh-fetch.
482 gitlink:git-update-server-info[1]::
483 Updates auxiliary information on a dumb server to help
484 clients discover references and packs on it.
486 gitlink:git-upload-archive[1]::
487 Invoked by 'git-archive' to send a generated archive.
489 gitlink:git-upload-pack[1]::
490 Invoked by 'git-fetch-pack' to push
491 what are asked for.
494 Configuration Mechanism
495 -----------------------
497 Starting from 0.99.9 (actually mid 0.99.8.GIT), `.git/config` file
498 is used to hold per-repository configuration options. It is a
499 simple text file modeled after `.ini` format familiar to some
500 people. Here is an example:
502 ------------
503 #
504 # A '#' or ';' character indicates a comment.
505 #
507 ; core variables
508 [core]
509 ; Don't trust file modes
510 filemode = false
512 ; user identity
513 [user]
514 name = "Junio C Hamano"
515 email = "junkio@twinsun.com"
517 ------------
519 Various commands read from the configuration file and adjust
520 their operation accordingly.
523 Identifier Terminology
524 ----------------------
525 <object>::
526 Indicates the object name for any type of object.
528 <blob>::
529 Indicates a blob object name.
531 <tree>::
532 Indicates a tree object name.
534 <commit>::
535 Indicates a commit object name.
537 <tree-ish>::
538 Indicates a tree, commit or tag object name. A
539 command that takes a <tree-ish> argument ultimately wants to
540 operate on a <tree> object but automatically dereferences
541 <commit> and <tag> objects that point at a <tree>.
543 <type>::
544 Indicates that an object type is required.
545 Currently one of: `blob`, `tree`, `commit`, or `tag`.
547 <file>::
548 Indicates a filename - almost always relative to the
549 root of the tree structure `GIT_INDEX_FILE` describes.
551 Symbolic Identifiers
552 --------------------
553 Any git command accepting any <object> can also use the following
554 symbolic notation:
556 HEAD::
557 indicates the head of the current branch (i.e. the
558 contents of `$GIT_DIR/HEAD`).
560 <tag>::
561 a valid tag 'name'
562 (i.e. the contents of `$GIT_DIR/refs/tags/<tag>`).
564 <head>::
565 a valid head 'name'
566 (i.e. the contents of `$GIT_DIR/refs/heads/<head>`).
568 For a more complete list of ways to spell object names, see
569 "SPECIFYING REVISIONS" section in gitlink:git-rev-parse[1].
572 File/Directory Structure
573 ------------------------
575 Please see link:repository-layout.html[repository layout] document.
577 Read link:hooks.html[hooks] for more details about each hook.
579 Higher level SCMs may provide and manage additional information in the
580 `$GIT_DIR`.
583 Terminology
584 -----------
585 Please see link:glossary.html[glossary] document.
588 Environment Variables
589 ---------------------
590 Various git commands use the following environment variables:
592 The git Repository
593 ~~~~~~~~~~~~~~~~~~
594 These environment variables apply to 'all' core git commands. Nb: it
595 is worth noting that they may be used/overridden by SCMS sitting above
596 git so take care if using Cogito etc.
598 'GIT_INDEX_FILE'::
599 This environment allows the specification of an alternate
600 index file. If not specified, the default of `$GIT_DIR/index`
601 is used.
603 'GIT_OBJECT_DIRECTORY'::
604 If the object storage directory is specified via this
605 environment variable then the sha1 directories are created
606 underneath - otherwise the default `$GIT_DIR/objects`
607 directory is used.
609 'GIT_ALTERNATE_OBJECT_DIRECTORIES'::
610 Due to the immutable nature of git objects, old objects can be
611 archived into shared, read-only directories. This variable
612 specifies a ":" separated list of git object directories which
613 can be used to search for git objects. New objects will not be
614 written to these directories.
616 'GIT_DIR'::
617 If the 'GIT_DIR' environment variable is set then it
618 specifies a path to use instead of the default `.git`
619 for the base of the repository.
621 git Commits
622 ~~~~~~~~~~~
623 'GIT_AUTHOR_NAME'::
624 'GIT_AUTHOR_EMAIL'::
625 'GIT_AUTHOR_DATE'::
626 'GIT_COMMITTER_NAME'::
627 'GIT_COMMITTER_EMAIL'::
628 see gitlink:git-commit-tree[1]
630 git Diffs
631 ~~~~~~~~~
632 'GIT_DIFF_OPTS'::
633 'GIT_EXTERNAL_DIFF'::
634 see the "generating patches" section in :
635 gitlink:git-diff-index[1];
636 gitlink:git-diff-files[1];
637 gitlink:git-diff-tree[1]
639 other
640 ~~~~~
641 'GIT_PAGER'::
642 This environment variable overrides `$PAGER`.
644 'GIT_TRACE'::
645 If this variable is set to "1", "2" or "true" (comparison
646 is case insensitive), git will print `trace:` messages on
647 stderr telling about alias expansion, built-in command
648 execution and external command execution.
649 If this variable is set to an integer value greater than 1
650 and lower than 10 (strictly) then git will interpret this
651 value as an open file descriptor and will try to write the
652 trace messages into this file descriptor.
653 Alternatively, if this variable is set to an absolute path
654 (starting with a '/' character), git will interpret this
655 as a file path and will try to write the trace messages
656 into it.
658 Discussion[[Discussion]]
659 ------------------------
660 include::README[]
662 Authors
663 -------
664 * git's founding father is Linus Torvalds <torvalds@osdl.org>.
665 * The current git nurse is Junio C Hamano <junkio@cox.net>.
666 * The git potty was written by Andres Ericsson <ae@op5.se>.
667 * General upbringing is handled by the git-list <git@vger.kernel.org>.
669 Documentation
670 --------------
671 The documentation for git suite was started by David Greaves
672 <david@dgreaves.com>, and later enhanced greatly by the
673 contributors on the git-list <git@vger.kernel.org>.
675 GIT
676 ---
677 Part of the gitlink:git[7] suite