1bf5ef57e41eaa74836f75d089a07c3a40f2837e
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-fsck-objects[1]::
164 Verifies the connectivity and validity of the objects in the database.
166 gitlink:git-ls-files[1]::
167 Information about files in the index and the working tree.
169 gitlink:git-ls-tree[1]::
170 Displays a tree object in human readable form.
172 gitlink:git-merge-base[1]::
173 Finds as good common ancestors as possible for a merge.
175 gitlink:git-name-rev[1]::
176 Find symbolic names for given revs.
178 gitlink:git-pack-redundant[1]::
179 Find redundant pack files.
181 gitlink:git-rev-list[1]::
182 Lists commit objects in reverse chronological order.
184 gitlink:git-show-index[1]::
185 Displays contents of a pack idx file.
187 gitlink:git-tar-tree[1]::
188 Creates a tar archive of the files in the named tree object.
190 gitlink:git-unpack-file[1]::
191 Creates a temporary file with a blob's contents.
193 gitlink:git-var[1]::
194 Displays a git logical variable.
196 gitlink:git-verify-pack[1]::
197 Validates packed git archive files.
199 In general, the interrogate commands do not touch the files in
200 the working tree.
203 Synching repositories
204 ~~~~~~~~~~~~~~~~~~~~~
206 gitlink:git-fetch-pack[1]::
207 Updates from a remote repository (engine for ssh and
208 local transport).
210 gitlink:git-http-fetch[1]::
211 Downloads a remote git repository via HTTP by walking
212 commit chain.
214 gitlink:git-local-fetch[1]::
215 Duplicates another git repository on a local system by
216 walking commit chain.
218 gitlink:git-peek-remote[1]::
219 Lists references on a remote repository using
220 upload-pack protocol (engine for ssh and local
221 transport).
223 gitlink:git-receive-pack[1]::
224 Invoked by 'git-send-pack' to receive what is pushed to it.
226 gitlink:git-send-pack[1]::
227 Pushes to a remote repository, intelligently.
229 gitlink:git-http-push[1]::
230 Push missing objects using HTTP/DAV.
232 gitlink:git-shell[1]::
233 Restricted shell for GIT-only SSH access.
235 gitlink:git-ssh-fetch[1]::
236 Pulls from a remote repository over ssh connection by
237 walking commit chain.
239 gitlink:git-ssh-upload[1]::
240 Helper "server-side" program used by git-ssh-fetch.
242 gitlink:git-update-server-info[1]::
243 Updates auxiliary information on a dumb server to help
244 clients discover references and packs on it.
246 gitlink:git-upload-pack[1]::
247 Invoked by 'git-fetch-pack' to push
248 what are asked for.
251 High-level commands (porcelain)
252 -------------------------------
254 We separate the porcelain commands into the main commands and some
255 ancillary user utilities.
257 Main porcelain commands
258 ~~~~~~~~~~~~~~~~~~~~~~~
260 gitlink:git-add[1]::
261 Add paths to the index.
263 gitlink:git-am[1]::
264 Apply patches from a mailbox, but cooler.
266 gitlink:git-applymbox[1]::
267 Apply patches from a mailbox, original version by Linus.
269 gitlink:git-bisect[1]::
270 Find the change that introduced a bug by binary search.
272 gitlink:git-branch[1]::
273 Create and Show branches.
275 gitlink:git-checkout[1]::
276 Checkout and switch to a branch.
278 gitlink:git-cherry-pick[1]::
279 Cherry-pick the effect of an existing commit.
281 gitlink:git-clean[1]::
282 Remove untracked files from the working tree.
284 gitlink:git-clone[1]::
285 Clones a repository into a new directory.
287 gitlink:git-commit[1]::
288 Record changes to the repository.
290 gitlink:git-diff[1]::
291 Show changes between commits, commit and working tree, etc.
293 gitlink:git-fetch[1]::
294 Download from a remote repository via various protocols.
296 gitlink:git-format-patch[1]::
297 Prepare patches for e-mail submission.
299 gitlink:git-grep[1]::
300 Print lines matching a pattern.
302 gitlink:gitk[1]::
303 The git repository browser.
305 gitlink:git-log[1]::
306 Shows commit logs.
308 gitlink:git-ls-remote[1]::
309 Shows references in a remote or local repository.
311 gitlink:git-merge[1]::
312 Grand unified merge driver.
314 gitlink:git-mv[1]::
315 Move or rename a file, a directory, or a symlink.
317 gitlink:git-pull[1]::
318 Fetch from and merge with a remote repository.
320 gitlink:git-push[1]::
321 Update remote refs along with associated objects.
323 gitlink:git-rebase[1]::
324 Rebase local commits to the updated upstream head.
326 gitlink:git-repack[1]::
327 Pack unpacked objects in a repository.
329 gitlink:git-rerere[1]::
330 Reuse recorded resolution of conflicted merges.
332 gitlink:git-reset[1]::
333 Reset current HEAD to the specified state.
335 gitlink:git-resolve[1]::
336 Merge two commits.
338 gitlink:git-revert[1]::
339 Revert an existing commit.
341 gitlink:git-rm[1]::
342 Remove files from the working tree and from the index.
344 gitlink:git-shortlog[1]::
345 Summarizes 'git log' output.
347 gitlink:git-show[1]::
348 Show one commit log and its diff.
350 gitlink:git-show-branch[1]::
351 Show branches and their commits.
353 gitlink:git-status[1]::
354 Shows the working tree status.
356 gitlink:git-verify-tag[1]::
357 Check the GPG signature of tag.
359 gitlink:git-whatchanged[1]::
360 Shows commit logs and differences they introduce.
363 Ancillary Commands
364 ~~~~~~~~~~~~~~~~~~
365 Manipulators:
367 gitlink:git-applypatch[1]::
368 Apply one patch extracted from an e-mail.
370 gitlink:git-archimport[1]::
371 Import an arch repository into git.
373 gitlink:git-convert-objects[1]::
374 Converts old-style git repository.
376 gitlink:git-cvsimport[1]::
377 Salvage your data out of another SCM people love to hate.
379 gitlink:git-cvsexportcommit[1]::
380 Export a single commit to a CVS checkout.
382 gitlink:git-cvsserver[1]::
383 A CVS server emulator for git.
385 gitlink:git-lost-found[1]::
386 Recover lost refs that luckily have not yet been pruned.
388 gitlink:git-merge-one-file[1]::
389 The standard helper program to use with `git-merge-index`.
391 gitlink:git-prune[1]::
392 Prunes all unreachable objects from the object database.
394 gitlink:git-quiltimport[1]::
395 Applies a quilt patchset onto the current branch.
397 gitlink:git-relink[1]::
398 Hardlink common objects in local repositories.
400 gitlink:git-svn[1]::
401 Bidirectional operation between a single Subversion branch and git.
403 gitlink:git-svnimport[1]::
404 Import a SVN repository into git.
406 gitlink:git-sh-setup[1]::
407 Common git shell script setup code.
409 gitlink:git-symbolic-ref[1]::
410 Read and modify symbolic refs.
412 gitlink:git-tag[1]::
413 An example script to create a tag object signed with GPG.
415 gitlink:git-update-ref[1]::
416 Update the object name stored in a ref safely.
419 Interrogators:
421 gitlink:git-annotate[1]::
422 Annotate file lines with commit info.
424 gitlink:git-blame[1]::
425 Blame file lines on commits.
427 gitlink:git-check-ref-format[1]::
428 Make sure ref name is well formed.
430 gitlink:git-cherry[1]::
431 Find commits not merged upstream.
433 gitlink:git-count-objects[1]::
434 Count unpacked number of objects and their disk consumption.
436 gitlink:git-daemon[1]::
437 A really simple server for git repositories.
439 gitlink:git-fmt-merge-msg[1]::
440 Produce a merge commit message.
442 gitlink:git-get-tar-commit-id[1]::
443 Extract commit ID from an archive created using git-tar-tree.
445 gitlink:git-imap-send[1]::
446 Dump a mailbox from stdin into an imap folder.
448 gitlink:git-instaweb[1]::
449 Instantly browse your working repository in gitweb.
451 gitlink:git-mailinfo[1]::
452 Extracts patch and authorship information from a single
453 e-mail message, optionally transliterating the commit
454 message into utf-8.
456 gitlink:git-mailsplit[1]::
457 A stupid program to split UNIX mbox format mailbox into
458 individual pieces of e-mail.
460 gitlink:git-merge-tree[1]::
461 Show three-way merge without touching index.
463 gitlink:git-patch-id[1]::
464 Compute unique ID for a patch.
466 gitlink:git-parse-remote[1]::
467 Routines to help parsing `$GIT_DIR/remotes/` files.
469 gitlink:git-request-pull[1]::
470 git-request-pull.
472 gitlink:git-rev-parse[1]::
473 Pick out and massage parameters.
475 gitlink:git-send-email[1]::
476 Send patch e-mails out of "format-patch --mbox" output.
478 gitlink:git-symbolic-ref[1]::
479 Read and modify symbolic refs.
481 gitlink:git-stripspace[1]::
482 Filter out empty lines.
485 Configuration Mechanism
486 -----------------------
488 Starting from 0.99.9 (actually mid 0.99.8.GIT), `.git/config` file
489 is used to hold per-repository configuration options. It is a
490 simple text file modeled after `.ini` format familiar to some
491 people. Here is an example:
493 ------------
494 #
495 # A '#' or ';' character indicates a comment.
496 #
498 ; core variables
499 [core]
500 ; Don't trust file modes
501 filemode = false
503 ; user identity
504 [user]
505 name = "Junio C Hamano"
506 email = "junkio@twinsun.com"
508 ------------
510 Various commands read from the configuration file and adjust
511 their operation accordingly.
514 Identifier Terminology
515 ----------------------
516 <object>::
517 Indicates the object name for any type of object.
519 <blob>::
520 Indicates a blob object name.
522 <tree>::
523 Indicates a tree object name.
525 <commit>::
526 Indicates a commit object name.
528 <tree-ish>::
529 Indicates a tree, commit or tag object name. A
530 command that takes a <tree-ish> argument ultimately wants to
531 operate on a <tree> object but automatically dereferences
532 <commit> and <tag> objects that point at a <tree>.
534 <type>::
535 Indicates that an object type is required.
536 Currently one of: `blob`, `tree`, `commit`, or `tag`.
538 <file>::
539 Indicates a filename - almost always relative to the
540 root of the tree structure `GIT_INDEX_FILE` describes.
542 Symbolic Identifiers
543 --------------------
544 Any git command accepting any <object> can also use the following
545 symbolic notation:
547 HEAD::
548 indicates the head of the current branch (i.e. the
549 contents of `$GIT_DIR/HEAD`).
551 <tag>::
552 a valid tag 'name'
553 (i.e. the contents of `$GIT_DIR/refs/tags/<tag>`).
555 <head>::
556 a valid head 'name'
557 (i.e. the contents of `$GIT_DIR/refs/heads/<head>`).
560 File/Directory Structure
561 ------------------------
563 Please see link:repository-layout.html[repository layout] document.
565 Read link:hooks.html[hooks] for more details about each hook.
567 Higher level SCMs may provide and manage additional information in the
568 `$GIT_DIR`.
571 Terminology
572 -----------
573 Please see link:glossary.html[glossary] document.
576 Environment Variables
577 ---------------------
578 Various git commands use the following environment variables:
580 The git Repository
581 ~~~~~~~~~~~~~~~~~~
582 These environment variables apply to 'all' core git commands. Nb: it
583 is worth noting that they may be used/overridden by SCMS sitting above
584 git so take care if using Cogito etc.
586 'GIT_INDEX_FILE'::
587 This environment allows the specification of an alternate
588 index file. If not specified, the default of `$GIT_DIR/index`
589 is used.
591 'GIT_OBJECT_DIRECTORY'::
592 If the object storage directory is specified via this
593 environment variable then the sha1 directories are created
594 underneath - otherwise the default `$GIT_DIR/objects`
595 directory is used.
597 'GIT_ALTERNATE_OBJECT_DIRECTORIES'::
598 Due to the immutable nature of git objects, old objects can be
599 archived into shared, read-only directories. This variable
600 specifies a ":" separated list of git object directories which
601 can be used to search for git objects. New objects will not be
602 written to these directories.
604 'GIT_DIR'::
605 If the 'GIT_DIR' environment variable is set then it
606 specifies a path to use instead of the default `.git`
607 for the base of the repository.
609 git Commits
610 ~~~~~~~~~~~
611 'GIT_AUTHOR_NAME'::
612 'GIT_AUTHOR_EMAIL'::
613 'GIT_AUTHOR_DATE'::
614 'GIT_COMMITTER_NAME'::
615 'GIT_COMMITTER_EMAIL'::
616 see gitlink:git-commit-tree[1]
618 git Diffs
619 ~~~~~~~~~
620 'GIT_DIFF_OPTS'::
621 'GIT_EXTERNAL_DIFF'::
622 see the "generating patches" section in :
623 gitlink:git-diff-index[1];
624 gitlink:git-diff-files[1];
625 gitlink:git-diff-tree[1]
627 other
628 ~~~~~
629 'GIT_PAGER'::
630 This environment variable overrides `$PAGER`.
632 'GIT_TRACE'::
633 If this variable is set to "1", "2" or "true" (comparison
634 is case insensitive), git will print `trace:` messages on
635 stderr telling about alias expansion, built-in command
636 execution and external command execution.
637 If this variable is set to an integer value greater than 1
638 and lower than 10 (strictly) then git will interpret this
639 value as an open file descriptor and will try to write the
640 trace messages into this file descriptor.
641 Alternatively, if this variable is set to an absolute path
642 (starting with a '/' character), git will interpret this
643 as a file path and will try to write the trace messages
644 into it.
646 Discussion[[Discussion]]
647 ------------------------
648 include::README[]
650 Authors
651 -------
652 * git's founding father is Linus Torvalds <torvalds@osdl.org>.
653 * The current git nurse is Junio C Hamano <junkio@cox.net>.
654 * The git potty was written by Andres Ericsson <ae@op5.se>.
655 * General upbringing is handled by the git-list <git@vger.kernel.org>.
657 Documentation
658 --------------
659 The documentation for git suite was started by David Greaves
660 <david@dgreaves.com>, and later enhanced greatly by the
661 contributors on the git-list <git@vger.kernel.org>.
663 GIT
664 ---
665 Part of the gitlink:git[7] suite