More useful/hinting error messages in git-checkout
[git/repo.git] / Documentation / git.txt
blob2d0ca9d8ed09cd247e87adbc7be17f25ead1a353
1 git(7)
2 ======
4 NAME
5 ----
6 git - the stupid content tracker
9 SYNOPSIS
10 --------
11 'git' [--version] [--exec-path[=GIT_EXEC_PATH]] [--help] COMMAND [ARGS]
13 DESCRIPTION
14 -----------
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).
20 OPTIONS
21 -------
22 --version::
23         prints the git suite version that the 'git' program came from.
25 --help::
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.
30 --exec-path::
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
53 internally work.
55 If you are migrating from CVS, link:cvs-migration.html[cvs
56 migration] document may be helpful after you finish the
57 tutorial.
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.
64 CORE GIT COMMANDS
65 -----------------
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].
72 Commands Overview
73 -----------------
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
81 Porcelains.
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.
87 Manipulation commands
88 ~~~~~~~~~~~~~~~~~~~~~
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
107         existing one.
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.
188 gitlink:git-var[1]::
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
195 the working tree.
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
207         local transport).
209 gitlink:git-http-fetch[1]::
210         Downloads a remote git repository via HTTP by walking
211         commit chain.
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
220         transport).
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
247         what are asked for.
250 Porcelain-ish Commands
251 ----------------------
253 gitlink:git-add[1]::
254         Add paths to the index.
256 gitlink:git-am[1]::
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.
292 gitlink:git-log[1]::
293         Shows commit logs.
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.
301 gitlink:git-mv[1]::
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]::
323         Merge two commits.
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.
344 Ancillary Commands
345 ------------------
346 Manipulators:
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.
384 gitlink:git-tag[1]::
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.
391 Interrogators:
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
411         message into utf-8.
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]::
424         git-request-pull.
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 ---------------------------
442 gitlink:gitk[1]::
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:
454 ------------
456 # A '#' or ';' character indicates a comment.
459 ; core variables
460 [core]
461         ; Don't trust file modes
462         filemode = false
464 ; user identity
465 [user]
466         name = "Junio C Hamano"
467         email = "junkio@twinsun.com"
469 ------------
471 Various commands read from the configuration file and adjust
472 their operation accordingly.
475 Identifier Terminology
476 ----------------------
477 <object>::
478         Indicates the object name for any type of object.
480 <blob>::
481         Indicates a blob object name.
483 <tree>::
484         Indicates a tree object name.
486 <commit>::
487         Indicates a commit object name.
489 <tree-ish>::
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>.
495 <type>::
496         Indicates that an object type is required.
497         Currently one of: `blob`, `tree`, `commit`, or `tag`.
499 <file>::
500         Indicates a filename - almost always relative to the
501         root of the tree structure `GIT_INDEX_FILE` describes.
503 Symbolic Identifiers
504 --------------------
505 Any git command accepting any <object> can also use the following
506 symbolic notation:
508 HEAD::
509         indicates the head of the current branch (i.e. the
510         contents of `$GIT_DIR/HEAD`).
512 <tag>::
513         a valid tag 'name'
514         (i.e. the contents of `$GIT_DIR/refs/tags/<tag>`).
516 <head>::
517         a valid head 'name'
518         (i.e. the contents of `$GIT_DIR/refs/heads/<head>`).
520 <snap>::
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
531 `$GIT_DIR`.
534 Terminology
535 -----------
536 Please see link:glossary.html[glossary] document.
539 Environment Variables
540 ---------------------
541 Various git commands use the following environment variables:
543 The git Repository
544 ~~~~~~~~~~~~~~~~~~
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.
549 'GIT_INDEX_FILE'::
550         This environment allows the specification of an alternate
551         index file. If not specified, the default of `$GIT_DIR/index`
552         is used.
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`
558         directory is used.
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.
567 'GIT_DIR'::
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.
572 git Commits
573 ~~~~~~~~~~~
574 'GIT_AUTHOR_NAME'::
575 'GIT_AUTHOR_EMAIL'::
576 'GIT_AUTHOR_DATE'::
577 'GIT_COMMITTER_NAME'::
578 'GIT_COMMITTER_EMAIL'::
579         see gitlink:git-commit-tree[1]
581 git Diffs
582 ~~~~~~~~~
583 'GIT_DIFF_OPTS'::
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 ------------------------
592 include::README[]
594 Authors
595 -------
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>.
601 Documentation
602 --------------
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