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.
38 Before reading this cover to cover, you may want to take a look
39 at the link:tutorial.html[tutorial] document.
41 The <<Discussion>> section below contains much useful definition
42 and clarification info - read that first. After that, if you
43 are interested in using git to manage (version control)
44 projects, read on commands listed in Porcelain-ish commands
45 section next. On the other hand, if you are writing your own
46 Porcelain, I suggest reading gitlink:git-update-index[1] and
47 gitlink:git-read-tree[1] first.
49 If you are migrating from CVS, link:cvs-migration.html[cvs migration]
50 document may be helpful after you finish the tutorial.
52 After you get the general feel from the tutorial and this
53 overview page, you may want to take a look at the
54 link:howto-index.html[howto] documents.
57 David Greaves <david@dgreaves.com>
60 Updated by Junio C Hamano <junkio@cox.net> on 2005-05-05 and
61 further on 2005-12-07 to reflect recent changes.
65 The git commands can helpfully be split into those that manipulate
66 the repository, the index and the files in the working tree, those that
67 interrogate and compare them, and those that moves objects and
68 references between repositories.
70 In addition, git itself comes with a spartan set of porcelain
71 commands. They are usable but are not meant to compete with real
74 There are also some ancillary programs that can be viewed as useful
75 aids for using the core commands but which are unlikely to be used by
76 SCMs layered over git.
80 gitlink:git-apply[1]::
81 Reads a "diff -up1" or git generated patch file and
82 applies it to the working tree.
84 gitlink:git-checkout-index[1]::
85 Copy files from the index to the working tree.
87 gitlink:git-commit-tree[1]::
88 Creates a new commit object.
90 gitlink:git-hash-object[1]::
91 Computes the object ID from a file.
93 gitlink:git-index-pack[1]::
94 Build pack idx file for an existing packed archive.
96 gitlink:git-init-db[1]::
97 Creates an empty git object database, or reinitialize an
100 gitlink:git-merge-index[1]::
101 Runs a merge for files needing merging.
103 gitlink:git-mktag[1]::
104 Creates a tag object.
106 gitlink:git-pack-objects[1]::
107 Creates a packed archive of objects.
109 gitlink:git-prune-packed[1]::
110 Remove extra objects that are already in pack files.
112 gitlink:git-read-tree[1]::
113 Reads tree information into the index.
115 gitlink:git-repo-config[1]::
116 Get and set options in .git/config.
118 gitlink:git-unpack-objects[1]::
119 Unpacks objects out of a packed archive.
121 gitlink:git-update-index[1]::
122 Registers files in the working tree to the index.
124 gitlink:git-write-tree[1]::
125 Creates a tree from the index.
128 Interrogation commands
129 ~~~~~~~~~~~~~~~~~~~~~~
131 gitlink:git-cat-file[1]::
132 Provide content or type/size information for repository objects.
134 gitlink:git-diff-index[1]::
135 Compares content and mode of blobs between the index and repository.
137 gitlink:git-diff-files[1]::
138 Compares files in the working tree and the index.
140 gitlink:git-diff-stages[1]::
141 Compares two "merge stages" in the index.
143 gitlink:git-diff-tree[1]::
144 Compares the content and mode of blobs found via two tree objects.
146 gitlink:git-fsck-objects[1]::
147 Verifies the connectivity and validity of the objects in the database.
149 gitlink:git-ls-files[1]::
150 Information about files in the index and the working tree.
152 gitlink:git-ls-tree[1]::
153 Displays a tree object in human readable form.
155 gitlink:git-merge-base[1]::
156 Finds as good common ancestors as possible for a merge.
158 gitlink:git-name-rev[1]::
159 Find symbolic names for given revs.
161 gitlink:git-rev-list[1]::
162 Lists commit objects in reverse chronological order.
164 gitlink:git-show-index[1]::
165 Displays contents of a pack idx file.
167 gitlink:git-tar-tree[1]::
168 Creates a tar archive of the files in the named tree object.
170 gitlink:git-unpack-file[1]::
171 Creates a temporary file with a blob's contents.
174 Displays a git logical variable.
176 gitlink:git-verify-pack[1]::
177 Validates packed git archive files.
179 In general, the interrogate commands do not touch the files in
183 Synching repositories
184 ~~~~~~~~~~~~~~~~~~~~~
186 gitlink:git-clone-pack[1]::
187 Clones a repository into the current repository (engine
188 for ssh and local transport).
190 gitlink:git-fetch-pack[1]::
191 Updates from a remote repository (engine for ssh and
194 gitlink:git-http-fetch[1]::
195 Downloads a remote git repository via HTTP by walking
198 gitlink:git-local-fetch[1]::
199 Duplicates another git repository on a local system by
200 walking commit chain.
202 gitlink:git-peek-remote[1]::
203 Lists references on a remote repository using
204 upload-pack protocol (engine for ssh and local
207 gitlink:git-receive-pack[1]::
208 Invoked by 'git-send-pack' to receive what is pushed to it.
210 gitlink:git-send-pack[1]::
211 Pushes to a remote repository, intelligently.
213 gitlink:git-shell[1]::
214 Restricted shell for GIT-only SSH access.
216 gitlink:git-ssh-fetch[1]::
217 Pulls from a remote repository over ssh connection by
218 walking commit chain.
220 gitlink:git-ssh-upload[1]::
221 Helper "server-side" program used by git-ssh-fetch.
223 gitlink:git-update-server-info[1]::
224 Updates auxiliary information on a dumb server to help
225 clients discover references and packs on it.
227 gitlink:git-upload-pack[1]::
228 Invoked by 'git-clone-pack' and 'git-fetch-pack' to push
232 Porcelain-ish Commands
233 ----------------------
236 Add paths to the index.
239 Apply patches from a mailbox, but cooler.
241 gitlink:git-applymbox[1]::
242 Apply patches from a mailbox, original version by Linus.
244 gitlink:git-bisect[1]::
245 Find the change that introduced a bug by binary search.
247 gitlink:git-branch[1]::
248 Create and Show branches.
250 gitlink:git-checkout[1]::
251 Checkout and switch to a branch.
253 gitlink:git-cherry-pick[1]::
254 Cherry-pick the effect of an existing commit.
256 gitlink:git-clone[1]::
257 Clones a repository into a new directory.
259 gitlink:git-commit[1]::
260 Record changes to the repository.
262 gitlink:git-diff[1]::
263 Show changes between commits, commit and working tree, etc.
265 gitlink:git-fetch[1]::
266 Download from a remote repository via various protocols.
268 gitlink:git-format-patch[1]::
269 Prepare patches for e-mail submission.
271 gitlink:git-grep[1]::
272 Print lines matching a pattern.
277 gitlink:git-ls-remote[1]::
278 Shows references in a remote or local repository.
280 gitlink:git-merge[1]::
281 Grand unified merge driver.
284 Move or rename a file, a directory, or a symlink.
286 gitlink:git-octopus[1]::
287 Merge more than two commits.
289 gitlink:git-pull[1]::
290 Fetch from and merge with a remote repository.
292 gitlink:git-push[1]::
293 Update remote refs along with associated objects.
295 gitlink:git-rebase[1]::
296 Rebase local commits to the updated upstream head.
298 gitlink:git-repack[1]::
299 Pack unpacked objects in a repository.
301 gitlink:git-reset[1]::
302 Reset current HEAD to the specified state.
304 gitlink:git-resolve[1]::
307 gitlink:git-revert[1]::
308 Revert an existing commit.
310 gitlink:git-shortlog[1]::
311 Summarizes 'git log' output.
313 gitlink:git-show-branch[1]::
314 Show branches and their commits.
316 gitlink:git-status[1]::
317 Shows the working tree status.
319 gitlink:git-verify-tag[1]::
320 Check the GPG signature of tag.
322 gitlink:git-whatchanged[1]::
323 Shows commit logs and differences they introduce.
330 gitlink:git-applypatch[1]::
331 Apply one patch extracted from an e-mail.
333 gitlink:git-archimport[1]::
334 Import an arch repository into git.
336 gitlink:git-convert-objects[1]::
337 Converts old-style git repository.
339 gitlink:git-cvsimport[1]::
340 Salvage your data out of another SCM people love to hate.
342 gitlink:git-lost-found[1]::
343 Recover lost refs that luckily have not yet been pruned.
345 gitlink:git-merge-one-file[1]::
346 The standard helper program to use with `git-merge-index`.
348 gitlink:git-prune[1]::
349 Prunes all unreachable objects from the object database.
351 gitlink:git-relink[1]::
352 Hardlink common objects in local repositories.
354 gitlink:git-svnimport[1]::
355 Import a SVN repository into git.
357 gitlink:git-sh-setup[1]::
358 Common git shell script setup code.
360 gitlink:git-symbolic-ref[1]::
361 Read and modify symbolic refs.
364 An example script to create a tag object signed with GPG.
366 gitlink:git-update-ref[1]::
367 Update the object name stored in a ref safely.
372 gitlink:git-check-ref-format[1]::
373 Make sure ref name is well formed.
375 gitlink:git-cherry[1]::
376 Find commits not merged upstream.
378 gitlink:git-count-objects[1]::
379 Count unpacked number of objects and their disk consumption.
381 gitlink:git-daemon[1]::
382 A really simple server for git repositories.
384 gitlink:git-get-tar-commit-id[1]::
385 Extract commit ID from an archive created using git-tar-tree.
387 gitlink:git-mailinfo[1]::
388 Extracts patch and authorship information from a single
389 e-mail message, optionally transliterating the commit
392 gitlink:git-mailsplit[1]::
393 A stupid program to split UNIX mbox format mailbox into
394 individual pieces of e-mail.
396 gitlink:git-patch-id[1]::
397 Compute unique ID for a patch.
399 gitlink:git-parse-remote[1]::
400 Routines to help parsing `$GIT_DIR/remotes/` files.
402 gitlink:git-request-pull[1]::
405 gitlink:git-rev-parse[1]::
406 Pick out and massage parameters.
408 gitlink:git-send-email[1]::
409 Send patch e-mails out of "format-patch --mbox" output.
411 gitlink:git-symbolic-refs[1]::
412 Read and modify symbolic refs.
414 gitlink:git-stripspace[1]::
415 Filter out empty lines.
418 Commands not yet documented
419 ---------------------------
422 The gitk repository browser.
425 Configuration Mechanism
426 -----------------------
428 Starting from 0.99.9 (actually mid 0.99.8.GIT), `.git/config` file
429 is used to hold per-repository configuration options. It is a
430 simple text file modelled after `.ini` format familiar to some
431 people. Here is an example:
435 # A '#' or ';' character indicates a comment.
440 ; Don't trust file modes
445 name = "Junio C Hamano"
446 email = "junkio@twinsun.com"
450 Various commands read from the configuration file and adjust
451 their operation accordingly.
454 Identifier Terminology
455 ----------------------
457 Indicates the object name for any type of object.
460 Indicates a blob object name.
463 Indicates a tree object name.
466 Indicates a commit object name.
469 Indicates a tree, commit or tag object name. A
470 command that takes a <tree-ish> argument ultimately wants to
471 operate on a <tree> object but automatically dereferences
472 <commit> and <tag> objects that point at a <tree>.
475 Indicates that an object type is required.
476 Currently one of: `blob`, `tree`, `commit`, or `tag`.
479 Indicates a filename - almost always relative to the
480 root of the tree structure `GIT_INDEX_FILE` describes.
484 Any git command accepting any <object> can also use the following
488 indicates the head of the current branch (i.e. the
489 contents of `$GIT_DIR/HEAD`).
493 (i.e. the contents of `$GIT_DIR/refs/tags/<tag>`).
497 (i.e. the contents of `$GIT_DIR/refs/heads/<head>`).
500 a valid snapshot 'name'
501 (i.e. the contents of `$GIT_DIR/refs/snap/<snap>`).
504 File/Directory Structure
505 ------------------------
507 Please see link:repository-layout.html[repository layout] document.
509 Higher level SCMs may provide and manage additional information in the
515 Please see link:glossary.html[glossary] document.
518 Environment Variables
519 ---------------------
520 Various git commands use the following environment variables:
524 These environment variables apply to 'all' core git commands. Nb: it
525 is worth noting that they may be used/overridden by SCMS sitting above
526 git so take care if using Cogito etc.
529 This environment allows the specification of an alternate
530 index file. If not specified, the default of `$GIT_DIR/index`
533 'GIT_OBJECT_DIRECTORY'::
534 If the object storage directory is specified via this
535 environment variable then the sha1 directories are created
536 underneath - otherwise the default `$GIT_DIR/objects`
539 'GIT_ALTERNATE_OBJECT_DIRECTORIES'::
540 Due to the immutable nature of git objects, old objects can be
541 archived into shared, read-only directories. This variable
542 specifies a ":" separated list of git object directories which
543 can be used to search for git objects. New objects will not be
544 written to these directories.
547 If the 'GIT_DIR' environment variable is set then it
548 specifies a path to use instead of the default `.git`
549 for the base of the repository.
556 'GIT_COMMITTER_NAME'::
557 'GIT_COMMITTER_EMAIL'::
558 see gitlink:git-commit-tree[1]
563 'GIT_EXTERNAL_DIFF'::
564 see the "generating patches" section in :
565 gitlink:git-diff-index[1];
566 gitlink:git-diff-files[1];
567 gitlink:git-diff-tree[1]
569 Discussion[[Discussion]]
570 ------------------------
575 git's founding father is Linus Torvalds <torvalds@osdl.org>.
576 The current git nurse is Junio C Hamano <junkio@cox.net>.
577 The git potty was written by Andres Ericsson <ae@op5.se>.
578 General upbringing is handled by the git-list <git@vger.kernel.org>.
582 Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
586 Part of the gitlink:git[7] suite