6 git - the stupid content tracker
11 'git' [--version] [--exec-path[=GIT_EXEC_PATH]] [--help] COMMAND [ARGS]
15 'git' is both a program and a directory content tracker system.
16 The program 'git' is just a wrapper to reach the core git programs
17 (or a potty if you like, as it's not exactly porcelain but still
18 brings your stuff to the plumbing).
23 prints the git suite version that the 'git' program came from.
26 prints the synopsis and a list of available commands.
27 If a git command is named this option will bring up the
28 man-page for that command.
31 path to wherever your core git programs are installed.
32 This can also be controlled by setting the GIT_EXEC_PATH
33 environment variable. If no path is given 'git' will print
34 the current setting and then exit.
37 NOT LEARNING CORE GIT COMMANDS
38 ------------------------------
40 This manual is intended to give complete background information
41 and internal workings of git, which may be too much for most
42 people. The <<Discussion>> section below contains much useful
43 definition and clarification - read that first.
45 If you are interested in using git to manage (version control)
46 projects, use link:tutorial.html[The Tutorial] to get you started,
47 and then link:everyday.html[Everyday GIT] as a guide to the
48 minimum set of commands you need to know for day-to-day work.
49 Most likely, that will get you started, and you can go a long
50 way without knowing the low level details too much.
52 The link:core-tutorial.html[Core tutorial] document covers how things
55 If you are migrating from CVS, link:cvs-migration.html[cvs
56 migration] document may be helpful after you finish the
59 After you get the general feel from the tutorial and this
60 overview page, you may want to take a look at the
61 link:howto-index.html[howto] documents.
67 If you are writing your own Porcelain, you need to be familiar
68 with most of the low level commands --- I suggest starting from
69 gitlink:git-update-index[1] and gitlink:git-read-tree[1].
74 The git commands can helpfully be split into those that manipulate
75 the repository, the index and the files in the working tree, those that
76 interrogate and compare them, and those that moves objects and
77 references between repositories.
79 In addition, git itself comes with a spartan set of porcelain
80 commands. They are usable but are not meant to compete with real
83 There are also some ancillary programs that can be viewed as useful
84 aids for using the core commands but which are unlikely to be used by
85 SCMs layered over git.
89 gitlink:git-apply[1]::
90 Reads a "diff -up1" or git generated patch file and
91 applies it to the working tree.
93 gitlink:git-checkout-index[1]::
94 Copy files from the index to the working tree.
96 gitlink:git-commit-tree[1]::
97 Creates a new commit object.
99 gitlink:git-hash-object[1]::
100 Computes the object ID from a file.
102 gitlink:git-index-pack[1]::
103 Build pack idx file for an existing packed archive.
105 gitlink:git-init-db[1]::
106 Creates an empty git object database, or reinitialize an
109 gitlink:git-merge-index[1]::
110 Runs a merge for files needing merging.
112 gitlink:git-mktag[1]::
113 Creates a tag object.
115 gitlink:git-pack-objects[1]::
116 Creates a packed archive of objects.
118 gitlink:git-prune-packed[1]::
119 Remove extra objects that are already in pack files.
121 gitlink:git-read-tree[1]::
122 Reads tree information into the index.
124 gitlink:git-repo-config[1]::
125 Get and set options in .git/config.
127 gitlink:git-unpack-objects[1]::
128 Unpacks objects out of a packed archive.
130 gitlink:git-update-index[1]::
131 Registers files in the working tree to the index.
133 gitlink:git-write-tree[1]::
134 Creates a tree from the index.
137 Interrogation commands
138 ~~~~~~~~~~~~~~~~~~~~~~
140 gitlink:git-cat-file[1]::
141 Provide content or type/size information for repository objects.
143 gitlink:git-describe[1]::
144 Show the most recent tag that is reachable from a commit.
146 gitlink:git-diff-index[1]::
147 Compares content and mode of blobs between the index and repository.
149 gitlink:git-diff-files[1]::
150 Compares files in the working tree and the index.
152 gitlink:git-diff-stages[1]::
153 Compares two "merge stages" in the index.
155 gitlink:git-diff-tree[1]::
156 Compares the content and mode of blobs found via two tree objects.
158 gitlink:git-fsck-objects[1]::
159 Verifies the connectivity and validity of the objects in the database.
161 gitlink:git-ls-files[1]::
162 Information about files in the index and the working tree.
164 gitlink:git-ls-tree[1]::
165 Displays a tree object in human readable form.
167 gitlink:git-merge-base[1]::
168 Finds as good common ancestors as possible for a merge.
170 gitlink:git-name-rev[1]::
171 Find symbolic names for given revs.
173 gitlink:git-pack-redundant[1]::
174 Find redundant pack files.
176 gitlink:git-rev-list[1]::
177 Lists commit objects in reverse chronological order.
179 gitlink:git-show-index[1]::
180 Displays contents of a pack idx file.
182 gitlink:git-tar-tree[1]::
183 Creates a tar archive of the files in the named tree object.
185 gitlink:git-unpack-file[1]::
186 Creates a temporary file with a blob's contents.
189 Displays a git logical variable.
191 gitlink:git-verify-pack[1]::
192 Validates packed git archive files.
194 In general, the interrogate commands do not touch the files in
198 Synching repositories
199 ~~~~~~~~~~~~~~~~~~~~~
201 gitlink:git-clone-pack[1]::
202 Clones a repository into the current repository (engine
203 for ssh and local transport).
205 gitlink:git-fetch-pack[1]::
206 Updates from a remote repository (engine for ssh and
209 gitlink:git-http-fetch[1]::
210 Downloads a remote git repository via HTTP by walking
213 gitlink:git-local-fetch[1]::
214 Duplicates another git repository on a local system by
215 walking commit chain.
217 gitlink:git-peek-remote[1]::
218 Lists references on a remote repository using
219 upload-pack protocol (engine for ssh and local
222 gitlink:git-receive-pack[1]::
223 Invoked by 'git-send-pack' to receive what is pushed to it.
225 gitlink:git-send-pack[1]::
226 Pushes to a remote repository, intelligently.
228 gitlink:git-http-push[1]::
229 Push missing objects using HTTP/DAV.
231 gitlink:git-shell[1]::
232 Restricted shell for GIT-only SSH access.
234 gitlink:git-ssh-fetch[1]::
235 Pulls from a remote repository over ssh connection by
236 walking commit chain.
238 gitlink:git-ssh-upload[1]::
239 Helper "server-side" program used by git-ssh-fetch.
241 gitlink:git-update-server-info[1]::
242 Updates auxiliary information on a dumb server to help
243 clients discover references and packs on it.
245 gitlink:git-upload-pack[1]::
246 Invoked by 'git-clone-pack' and 'git-fetch-pack' to push
250 Porcelain-ish Commands
251 ----------------------
254 Add paths to the index.
257 Apply patches from a mailbox, but cooler.
259 gitlink:git-applymbox[1]::
260 Apply patches from a mailbox, original version by Linus.
262 gitlink:git-bisect[1]::
263 Find the change that introduced a bug by binary search.
265 gitlink:git-branch[1]::
266 Create and Show branches.
268 gitlink:git-checkout[1]::
269 Checkout and switch to a branch.
271 gitlink:git-cherry-pick[1]::
272 Cherry-pick the effect of an existing commit.
274 gitlink:git-clone[1]::
275 Clones a repository into a new directory.
277 gitlink:git-commit[1]::
278 Record changes to the repository.
280 gitlink:git-diff[1]::
281 Show changes between commits, commit and working tree, etc.
283 gitlink:git-fetch[1]::
284 Download from a remote repository via various protocols.
286 gitlink:git-format-patch[1]::
287 Prepare patches for e-mail submission.
289 gitlink:git-grep[1]::
290 Print lines matching a pattern.
295 gitlink:git-ls-remote[1]::
296 Shows references in a remote or local repository.
298 gitlink:git-merge[1]::
299 Grand unified merge driver.
302 Move or rename a file, a directory, or a symlink.
304 gitlink:git-pull[1]::
305 Fetch from and merge with a remote repository.
307 gitlink:git-push[1]::
308 Update remote refs along with associated objects.
310 gitlink:git-rebase[1]::
311 Rebase local commits to the updated upstream head.
313 gitlink:git-repack[1]::
314 Pack unpacked objects in a repository.
316 gitlink:git-rerere[1]::
317 Reuse recorded resolution of conflicted merges.
319 gitlink:git-reset[1]::
320 Reset current HEAD to the specified state.
322 gitlink:git-resolve[1]::
325 gitlink:git-revert[1]::
326 Revert an existing commit.
328 gitlink:git-shortlog[1]::
329 Summarizes 'git log' output.
331 gitlink:git-show-branch[1]::
332 Show branches and their commits.
334 gitlink:git-status[1]::
335 Shows the working tree status.
337 gitlink:git-verify-tag[1]::
338 Check the GPG signature of tag.
340 gitlink:git-whatchanged[1]::
341 Shows commit logs and differences they introduce.
348 gitlink:git-applypatch[1]::
349 Apply one patch extracted from an e-mail.
351 gitlink:git-archimport[1]::
352 Import an arch repository into git.
354 gitlink:git-convert-objects[1]::
355 Converts old-style git repository.
357 gitlink:git-cvsimport[1]::
358 Salvage your data out of another SCM people love to hate.
360 gitlink:git-cvsexportcommit[1]::
361 Export a single commit to a CVS checkout.
363 gitlink:git-lost-found[1]::
364 Recover lost refs that luckily have not yet been pruned.
366 gitlink:git-merge-one-file[1]::
367 The standard helper program to use with `git-merge-index`.
369 gitlink:git-prune[1]::
370 Prunes all unreachable objects from the object database.
372 gitlink:git-relink[1]::
373 Hardlink common objects in local repositories.
375 gitlink:git-svnimport[1]::
376 Import a SVN repository into git.
378 gitlink:git-sh-setup[1]::
379 Common git shell script setup code.
381 gitlink:git-symbolic-ref[1]::
382 Read and modify symbolic refs.
385 An example script to create a tag object signed with GPG.
387 gitlink:git-update-ref[1]::
388 Update the object name stored in a ref safely.
393 gitlink:git-check-ref-format[1]::
394 Make sure ref name is well formed.
396 gitlink:git-cherry[1]::
397 Find commits not merged upstream.
399 gitlink:git-count-objects[1]::
400 Count unpacked number of objects and their disk consumption.
402 gitlink:git-daemon[1]::
403 A really simple server for git repositories.
405 gitlink:git-get-tar-commit-id[1]::
406 Extract commit ID from an archive created using git-tar-tree.
408 gitlink:git-mailinfo[1]::
409 Extracts patch and authorship information from a single
410 e-mail message, optionally transliterating the commit
413 gitlink:git-mailsplit[1]::
414 A stupid program to split UNIX mbox format mailbox into
415 individual pieces of e-mail.
417 gitlink:git-patch-id[1]::
418 Compute unique ID for a patch.
420 gitlink:git-parse-remote[1]::
421 Routines to help parsing `$GIT_DIR/remotes/` files.
423 gitlink:git-request-pull[1]::
426 gitlink:git-rev-parse[1]::
427 Pick out and massage parameters.
429 gitlink:git-send-email[1]::
430 Send patch e-mails out of "format-patch --mbox" output.
432 gitlink:git-symbolic-ref[1]::
433 Read and modify symbolic refs.
435 gitlink:git-stripspace[1]::
436 Filter out empty lines.
439 Commands not yet documented
440 ---------------------------
443 The gitk repository browser.
446 Configuration Mechanism
447 -----------------------
449 Starting from 0.99.9 (actually mid 0.99.8.GIT), `.git/config` file
450 is used to hold per-repository configuration options. It is a
451 simple text file modelled after `.ini` format familiar to some
452 people. Here is an example:
456 # A '#' or ';' character indicates a comment.
461 ; Don't trust file modes
466 name = "Junio C Hamano"
467 email = "junkio@twinsun.com"
471 Various commands read from the configuration file and adjust
472 their operation accordingly.
475 Identifier Terminology
476 ----------------------
478 Indicates the object name for any type of object.
481 Indicates a blob object name.
484 Indicates a tree object name.
487 Indicates a commit object name.
490 Indicates a tree, commit or tag object name. A
491 command that takes a <tree-ish> argument ultimately wants to
492 operate on a <tree> object but automatically dereferences
493 <commit> and <tag> objects that point at a <tree>.
496 Indicates that an object type is required.
497 Currently one of: `blob`, `tree`, `commit`, or `tag`.
500 Indicates a filename - almost always relative to the
501 root of the tree structure `GIT_INDEX_FILE` describes.
505 Any git command accepting any <object> can also use the following
509 indicates the head of the current branch (i.e. the
510 contents of `$GIT_DIR/HEAD`).
514 (i.e. the contents of `$GIT_DIR/refs/tags/<tag>`).
518 (i.e. the contents of `$GIT_DIR/refs/heads/<head>`).
521 a valid snapshot 'name'
522 (i.e. the contents of `$GIT_DIR/refs/snap/<snap>`).
525 File/Directory Structure
526 ------------------------
528 Please see link:repository-layout.html[repository layout] document.
530 Higher level SCMs may provide and manage additional information in the
536 Please see link:glossary.html[glossary] document.
539 Environment Variables
540 ---------------------
541 Various git commands use the following environment variables:
545 These environment variables apply to 'all' core git commands. Nb: it
546 is worth noting that they may be used/overridden by SCMS sitting above
547 git so take care if using Cogito etc.
550 This environment allows the specification of an alternate
551 index file. If not specified, the default of `$GIT_DIR/index`
554 'GIT_OBJECT_DIRECTORY'::
555 If the object storage directory is specified via this
556 environment variable then the sha1 directories are created
557 underneath - otherwise the default `$GIT_DIR/objects`
560 'GIT_ALTERNATE_OBJECT_DIRECTORIES'::
561 Due to the immutable nature of git objects, old objects can be
562 archived into shared, read-only directories. This variable
563 specifies a ":" separated list of git object directories which
564 can be used to search for git objects. New objects will not be
565 written to these directories.
568 If the 'GIT_DIR' environment variable is set then it
569 specifies a path to use instead of the default `.git`
570 for the base of the repository.
577 'GIT_COMMITTER_NAME'::
578 'GIT_COMMITTER_EMAIL'::
579 see gitlink:git-commit-tree[1]
584 'GIT_EXTERNAL_DIFF'::
585 see the "generating patches" section in :
586 gitlink:git-diff-index[1];
587 gitlink:git-diff-files[1];
588 gitlink:git-diff-tree[1]
590 Discussion[[Discussion]]
591 ------------------------
596 * git's founding father is Linus Torvalds <torvalds@osdl.org>.
597 * The current git nurse is Junio C Hamano <junkio@cox.net>.
598 * The git potty was written by Andres Ericsson <ae@op5.se>.
599 * General upbringing is handled by the git-list <git@vger.kernel.org>.
603 The documentation for git suite was started by David Greaves
604 <david@dgreaves.com>, and later enhanced greatly by the
605 contributors on the git-list <git@vger.kernel.org>.
609 Part of the gitlink:git[7] suite