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-reset[1]::
317 Reset current HEAD to the specified state.
319 gitlink:git-resolve[1]::
322 gitlink:git-revert[1]::
323 Revert an existing commit.
325 gitlink:git-shortlog[1]::
326 Summarizes 'git log' output.
328 gitlink:git-show-branch[1]::
329 Show branches and their commits.
331 gitlink:git-status[1]::
332 Shows the working tree status.
334 gitlink:git-verify-tag[1]::
335 Check the GPG signature of tag.
337 gitlink:git-whatchanged[1]::
338 Shows commit logs and differences they introduce.
345 gitlink:git-applypatch[1]::
346 Apply one patch extracted from an e-mail.
348 gitlink:git-archimport[1]::
349 Import an arch repository into git.
351 gitlink:git-convert-objects[1]::
352 Converts old-style git repository.
354 gitlink:git-cvsimport[1]::
355 Salvage your data out of another SCM people love to hate.
357 gitlink:git-cvsexportcommit[1]::
358 Export a single commit to a CVS checkout.
360 gitlink:git-lost-found[1]::
361 Recover lost refs that luckily have not yet been pruned.
363 gitlink:git-merge-one-file[1]::
364 The standard helper program to use with `git-merge-index`.
366 gitlink:git-prune[1]::
367 Prunes all unreachable objects from the object database.
369 gitlink:git-relink[1]::
370 Hardlink common objects in local repositories.
372 gitlink:git-svnimport[1]::
373 Import a SVN repository into git.
375 gitlink:git-sh-setup[1]::
376 Common git shell script setup code.
378 gitlink:git-symbolic-ref[1]::
379 Read and modify symbolic refs.
382 An example script to create a tag object signed with GPG.
384 gitlink:git-update-ref[1]::
385 Update the object name stored in a ref safely.
390 gitlink:git-check-ref-format[1]::
391 Make sure ref name is well formed.
393 gitlink:git-cherry[1]::
394 Find commits not merged upstream.
396 gitlink:git-count-objects[1]::
397 Count unpacked number of objects and their disk consumption.
399 gitlink:git-daemon[1]::
400 A really simple server for git repositories.
402 gitlink:git-get-tar-commit-id[1]::
403 Extract commit ID from an archive created using git-tar-tree.
405 gitlink:git-mailinfo[1]::
406 Extracts patch and authorship information from a single
407 e-mail message, optionally transliterating the commit
410 gitlink:git-mailsplit[1]::
411 A stupid program to split UNIX mbox format mailbox into
412 individual pieces of e-mail.
414 gitlink:git-patch-id[1]::
415 Compute unique ID for a patch.
417 gitlink:git-parse-remote[1]::
418 Routines to help parsing `$GIT_DIR/remotes/` files.
420 gitlink:git-request-pull[1]::
423 gitlink:git-rev-parse[1]::
424 Pick out and massage parameters.
426 gitlink:git-send-email[1]::
427 Send patch e-mails out of "format-patch --mbox" output.
429 gitlink:git-symbolic-ref[1]::
430 Read and modify symbolic refs.
432 gitlink:git-stripspace[1]::
433 Filter out empty lines.
436 Commands not yet documented
437 ---------------------------
440 The gitk repository browser.
443 Configuration Mechanism
444 -----------------------
446 Starting from 0.99.9 (actually mid 0.99.8.GIT), `.git/config` file
447 is used to hold per-repository configuration options. It is a
448 simple text file modelled after `.ini` format familiar to some
449 people. Here is an example:
453 # A '#' or ';' character indicates a comment.
458 ; Don't trust file modes
463 name = "Junio C Hamano"
464 email = "junkio@twinsun.com"
468 Various commands read from the configuration file and adjust
469 their operation accordingly.
472 Identifier Terminology
473 ----------------------
475 Indicates the object name for any type of object.
478 Indicates a blob object name.
481 Indicates a tree object name.
484 Indicates a commit object name.
487 Indicates a tree, commit or tag object name. A
488 command that takes a <tree-ish> argument ultimately wants to
489 operate on a <tree> object but automatically dereferences
490 <commit> and <tag> objects that point at a <tree>.
493 Indicates that an object type is required.
494 Currently one of: `blob`, `tree`, `commit`, or `tag`.
497 Indicates a filename - almost always relative to the
498 root of the tree structure `GIT_INDEX_FILE` describes.
502 Any git command accepting any <object> can also use the following
506 indicates the head of the current branch (i.e. the
507 contents of `$GIT_DIR/HEAD`).
511 (i.e. the contents of `$GIT_DIR/refs/tags/<tag>`).
515 (i.e. the contents of `$GIT_DIR/refs/heads/<head>`).
518 a valid snapshot 'name'
519 (i.e. the contents of `$GIT_DIR/refs/snap/<snap>`).
522 File/Directory Structure
523 ------------------------
525 Please see link:repository-layout.html[repository layout] document.
527 Higher level SCMs may provide and manage additional information in the
533 Please see link:glossary.html[glossary] document.
536 Environment Variables
537 ---------------------
538 Various git commands use the following environment variables:
542 These environment variables apply to 'all' core git commands. Nb: it
543 is worth noting that they may be used/overridden by SCMS sitting above
544 git so take care if using Cogito etc.
547 This environment allows the specification of an alternate
548 index file. If not specified, the default of `$GIT_DIR/index`
551 'GIT_OBJECT_DIRECTORY'::
552 If the object storage directory is specified via this
553 environment variable then the sha1 directories are created
554 underneath - otherwise the default `$GIT_DIR/objects`
557 'GIT_ALTERNATE_OBJECT_DIRECTORIES'::
558 Due to the immutable nature of git objects, old objects can be
559 archived into shared, read-only directories. This variable
560 specifies a ":" separated list of git object directories which
561 can be used to search for git objects. New objects will not be
562 written to these directories.
565 If the 'GIT_DIR' environment variable is set then it
566 specifies a path to use instead of the default `.git`
567 for the base of the repository.
574 'GIT_COMMITTER_NAME'::
575 'GIT_COMMITTER_EMAIL'::
576 see gitlink:git-commit-tree[1]
581 'GIT_EXTERNAL_DIFF'::
582 see the "generating patches" section in :
583 gitlink:git-diff-index[1];
584 gitlink:git-diff-files[1];
585 gitlink:git-diff-tree[1]
587 Discussion[[Discussion]]
588 ------------------------
593 * git's founding father is Linus Torvalds <torvalds@osdl.org>.
594 * The current git nurse is Junio C Hamano <junkio@cox.net>.
595 * The git potty was written by Andres Ericsson <ae@op5.se>.
596 * General upbringing is handled by the git-list <git@vger.kernel.org>.
600 The documentation for git suite was started by David Greaves
601 <david@dgreaves.com>, and later enhanced greatly by the
602 contributors on the git-list <git@vger.kernel.org>.
606 Part of the gitlink:git[7] suite