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 Low-level commands (plumbing)
76 -----------------------------
78 Although git includes its
79 own porcelain layer, its low-level commands are sufficient to support
80 development of alternative porcelains. Developers of such porcelains
81 might start by reading about gitlink:git-update-index[1] and
82 gitlink:git-read-tree[1].
84 We divide the low-level commands into commands that manipulate objects (in
85 the repository, index, and working tree), commands that interrogate and
86 compare objects, and commands that move objects and references between
87 repositories.
89 Manipulation commands
90 ~~~~~~~~~~~~~~~~~~~~~
91 gitlink:git-apply[1]::
92 Reads a "diff -up1" or git generated patch file and
93 applies it to the working tree.
95 gitlink:git-checkout-index[1]::
96 Copy files from the index to the working tree.
98 gitlink:git-commit-tree[1]::
99 Creates a new commit object.
101 gitlink:git-hash-object[1]::
102 Computes the object ID from a file.
104 gitlink:git-index-pack[1]::
105 Build pack idx file for an existing packed archive.
107 gitlink:git-init-db[1]::
108 Creates an empty git object database, or reinitialize an
109 existing one.
111 gitlink:git-merge-index[1]::
112 Runs a merge for files needing merging.
114 gitlink:git-mktag[1]::
115 Creates a tag object.
117 gitlink:git-mktree[1]::
118 Build a tree-object from ls-tree formatted text.
120 gitlink:git-pack-objects[1]::
121 Creates a packed archive of objects.
123 gitlink:git-prune-packed[1]::
124 Remove extra objects that are already in pack files.
126 gitlink:git-read-tree[1]::
127 Reads tree information into the index.
129 gitlink:git-repo-config[1]::
130 Get and set options in .git/config.
132 gitlink:git-unpack-objects[1]::
133 Unpacks objects out of a packed archive.
135 gitlink:git-update-index[1]::
136 Registers files in the working tree to the index.
138 gitlink:git-write-tree[1]::
139 Creates a tree from the index.
142 Interrogation commands
143 ~~~~~~~~~~~~~~~~~~~~~~
145 gitlink:git-cat-file[1]::
146 Provide content or type/size information for repository objects.
148 gitlink:git-describe[1]::
149 Show the most recent tag that is reachable from a commit.
151 gitlink:git-diff-index[1]::
152 Compares content and mode of blobs between the index and repository.
154 gitlink:git-diff-files[1]::
155 Compares files in the working tree and the index.
157 gitlink:git-diff-stages[1]::
158 Compares two "merge stages" in the index.
160 gitlink:git-diff-tree[1]::
161 Compares the content and mode of blobs found via two tree objects.
163 gitlink:git-for-each-ref[1]::
164 Output information on each ref.
166 gitlink:git-fsck-objects[1]::
167 Verifies the connectivity and validity of the objects in the database.
169 gitlink:git-ls-files[1]::
170 Information about files in the index and the working tree.
172 gitlink:git-ls-tree[1]::
173 Displays a tree object in human readable form.
175 gitlink:git-merge-base[1]::
176 Finds as good common ancestors as possible for a merge.
178 gitlink:git-name-rev[1]::
179 Find symbolic names for given revs.
181 gitlink:git-pack-redundant[1]::
182 Find redundant pack files.
184 gitlink:git-rev-list[1]::
185 Lists commit objects in reverse chronological order.
187 gitlink:git-show-index[1]::
188 Displays contents of a pack idx file.
190 gitlink:git-tar-tree[1]::
191 Creates a tar archive of the files in the named tree object.
193 gitlink:git-unpack-file[1]::
194 Creates a temporary file with a blob's contents.
196 gitlink:git-var[1]::
197 Displays a git logical variable.
199 gitlink:git-verify-pack[1]::
200 Validates packed git archive files.
202 In general, the interrogate commands do not touch the files in
203 the working tree.
206 Synching repositories
207 ~~~~~~~~~~~~~~~~~~~~~
209 gitlink:git-fetch-pack[1]::
210 Updates from a remote repository (engine for ssh and
211 local transport).
213 gitlink:git-http-fetch[1]::
214 Downloads a remote git repository via HTTP by walking
215 commit chain.
217 gitlink:git-local-fetch[1]::
218 Duplicates another git repository on a local system by
219 walking commit chain.
221 gitlink:git-peek-remote[1]::
222 Lists references on a remote repository using
223 upload-pack protocol (engine for ssh and local
224 transport).
226 gitlink:git-receive-pack[1]::
227 Invoked by 'git-send-pack' to receive what is pushed to it.
229 gitlink:git-send-pack[1]::
230 Pushes to a remote repository, intelligently.
232 gitlink:git-http-push[1]::
233 Push missing objects using HTTP/DAV.
235 gitlink:git-shell[1]::
236 Restricted shell for GIT-only SSH access.
238 gitlink:git-ssh-fetch[1]::
239 Pulls from a remote repository over ssh connection by
240 walking commit chain.
242 gitlink:git-ssh-upload[1]::
243 Helper "server-side" program used by git-ssh-fetch.
245 gitlink:git-update-server-info[1]::
246 Updates auxiliary information on a dumb server to help
247 clients discover references and packs on it.
249 gitlink:git-upload-archive[1]::
250 Invoked by 'git-archive' to send a generated archive.
252 gitlink:git-upload-pack[1]::
253 Invoked by 'git-fetch-pack' to push
254 what are asked for.
257 High-level commands (porcelain)
258 -------------------------------
260 We separate the porcelain commands into the main commands and some
261 ancillary user utilities.
263 Main porcelain commands
264 ~~~~~~~~~~~~~~~~~~~~~~~
266 gitlink:git-add[1]::
267 Add paths to the index.
269 gitlink:git-am[1]::
270 Apply patches from a mailbox, but cooler.
272 gitlink:git-applymbox[1]::
273 Apply patches from a mailbox, original version by Linus.
275 gitlink:git-archive[1]::
276 Creates an archive of files from a named tree.
278 gitlink:git-bisect[1]::
279 Find the change that introduced a bug by binary search.
281 gitlink:git-branch[1]::
282 Create and Show branches.
284 gitlink:git-checkout[1]::
285 Checkout and switch to a branch.
287 gitlink:git-cherry-pick[1]::
288 Cherry-pick the effect of an existing commit.
290 gitlink:git-clean[1]::
291 Remove untracked files from the working tree.
293 gitlink:git-clone[1]::
294 Clones a repository into a new directory.
296 gitlink:git-commit[1]::
297 Record changes to the repository.
299 gitlink:git-diff[1]::
300 Show changes between commits, commit and working tree, etc.
302 gitlink:git-fetch[1]::
303 Download from a remote repository via various protocols.
305 gitlink:git-format-patch[1]::
306 Prepare patches for e-mail submission.
308 gitlink:git-grep[1]::
309 Print lines matching a pattern.
311 gitlink:gitk[1]::
312 The git repository browser.
314 gitlink:git-log[1]::
315 Shows commit logs.
317 gitlink:git-ls-remote[1]::
318 Shows references in a remote or local repository.
320 gitlink:git-merge[1]::
321 Grand unified merge driver.
323 gitlink:git-mv[1]::
324 Move or rename a file, a directory, or a symlink.
326 gitlink:git-pull[1]::
327 Fetch from and merge with a remote repository or a local branch.
329 gitlink:git-push[1]::
330 Update remote refs along with associated objects.
332 gitlink:git-rebase[1]::
333 Rebase local commits to the updated upstream head.
335 gitlink:git-repack[1]::
336 Pack unpacked objects in a repository.
338 gitlink:git-rerere[1]::
339 Reuse recorded resolution of conflicted merges.
341 gitlink:git-reset[1]::
342 Reset current HEAD to the specified state.
344 gitlink:git-resolve[1]::
345 Merge two commits.
347 gitlink:git-revert[1]::
348 Revert an existing commit.
350 gitlink:git-rm[1]::
351 Remove files from the working tree and from the index.
353 gitlink:git-shortlog[1]::
354 Summarizes 'git log' output.
356 gitlink:git-show[1]::
357 Show one commit log and its diff.
359 gitlink:git-show-branch[1]::
360 Show branches and their commits.
362 gitlink:git-status[1]::
363 Shows the working tree status.
365 gitlink:git-verify-tag[1]::
366 Check the GPG signature of tag.
368 gitlink:git-whatchanged[1]::
369 Shows commit logs and differences they introduce.
372 Ancillary Commands
373 ~~~~~~~~~~~~~~~~~~
374 Manipulators:
376 gitlink:git-applypatch[1]::
377 Apply one patch extracted from an e-mail.
379 gitlink:git-archimport[1]::
380 Import an arch repository into git.
382 gitlink:git-convert-objects[1]::
383 Converts old-style git repository.
385 gitlink:git-cvsimport[1]::
386 Salvage your data out of another SCM people love to hate.
388 gitlink:git-cvsexportcommit[1]::
389 Export a single commit to a CVS checkout.
391 gitlink:git-cvsserver[1]::
392 A CVS server emulator for git.
394 gitlink:git-lost-found[1]::
395 Recover lost refs that luckily have not yet been pruned.
397 gitlink:git-merge-one-file[1]::
398 The standard helper program to use with `git-merge-index`.
400 gitlink:git-prune[1]::
401 Prunes all unreachable objects from the object database.
403 gitlink:git-quiltimport[1]::
404 Applies a quilt patchset onto the current branch.
406 gitlink:git-relink[1]::
407 Hardlink common objects in local repositories.
409 gitlink:git-svn[1]::
410 Bidirectional operation between a single Subversion branch and git.
412 gitlink:git-svnimport[1]::
413 Import a SVN repository into git.
415 gitlink:git-sh-setup[1]::
416 Common git shell script setup code.
418 gitlink:git-symbolic-ref[1]::
419 Read and modify symbolic refs.
421 gitlink:git-tag[1]::
422 An example script to create a tag object signed with GPG.
424 gitlink:git-update-ref[1]::
425 Update the object name stored in a ref safely.
428 Interrogators:
430 gitlink:git-annotate[1]::
431 Annotate file lines with commit info.
433 gitlink:git-blame[1]::
434 Blame file lines on commits.
436 gitlink:git-check-ref-format[1]::
437 Make sure ref name is well formed.
439 gitlink:git-cherry[1]::
440 Find commits not merged upstream.
442 gitlink:git-count-objects[1]::
443 Count unpacked number of objects and their disk consumption.
445 gitlink:git-daemon[1]::
446 A really simple server for git repositories.
448 gitlink:git-fmt-merge-msg[1]::
449 Produce a merge commit message.
451 gitlink:git-get-tar-commit-id[1]::
452 Extract commit ID from an archive created using git-tar-tree.
454 gitlink:git-imap-send[1]::
455 Dump a mailbox from stdin into an imap folder.
457 gitlink:git-instaweb[1]::
458 Instantly browse your working repository in gitweb.
460 gitlink:git-mailinfo[1]::
461 Extracts patch and authorship information from a single
462 e-mail message, optionally transliterating the commit
463 message into utf-8.
465 gitlink:git-mailsplit[1]::
466 A stupid program to split UNIX mbox format mailbox into
467 individual pieces of e-mail.
469 gitlink:git-merge-tree[1]::
470 Show three-way merge without touching index.
472 gitlink:git-patch-id[1]::
473 Compute unique ID for a patch.
475 gitlink:git-parse-remote[1]::
476 Routines to help parsing `$GIT_DIR/remotes/` files.
478 gitlink:git-request-pull[1]::
479 git-request-pull.
481 gitlink:git-rev-parse[1]::
482 Pick out and massage parameters.
484 gitlink:git-send-email[1]::
485 Send patch e-mails out of "format-patch --mbox" output.
487 gitlink:git-symbolic-ref[1]::
488 Read and modify symbolic refs.
490 gitlink:git-stripspace[1]::
491 Filter out empty lines.
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