.SH "SYNOPSIS"
-git [\-\-version] [\-\-exec\-path[=GIT_EXEC_PATH]] [\-\-help] COMMAND [ARGS]
+\fIgit\fR [\-\-version] [\-\-exec\-path[=GIT_EXEC_PATH]] [\-\-help] COMMAND [ARGS]
.SH "DESCRIPTION"
-git is both a program and a directory content tracker system\&. The program git is just a wrapper to reach the core git programs (or a potty if you like, as it's not exactly porcelain but still brings your stuff to the plumbing)\&.
+\fIgit\fR is both a program and a directory content tracker system\&. The program \fIgit\fR is just a wrapper to reach the core git programs (or a potty if you like, as it's not exactly porcelain but still brings your stuff to the plumbing)\&.
.SH "OPTIONS"
.TP
\-\-version
-prints the git suite version that the git program came from\&.
+Prints the git suite version that the \fIgit\fR program came from\&.
.TP
\-\-help
-prints the synopsis and a list of available commands\&. If a git command is named this option will bring up the man\-page for that command\&.
+Prints the synopsis and a list of the most commonly used commands\&. If a git command is named this option will bring up the man\-page for that command\&. If the option \fI\-\-all\fR or \fI\-a\fR is given then all available commands are printed\&.
.TP
\-\-exec\-path
-path to wherever your core git programs are installed\&. This can also be controlled by setting the GIT_EXEC_PATH environment variable\&. If no path is given git will print the current setting and then exit\&.
+Path to wherever your core git programs are installed\&. This can also be controlled by setting the GIT_EXEC_PATH environment variable\&. If no path is given \fIgit\fR will print the current setting and then exit\&.
.SH "NOT LEARNING CORE GIT COMMANDS"
This manual is intended to give complete background information and internal workings of git, which may be too much for most people\&. The [xref to anchor] section below contains much useful definition and clarification \- read that first\&.
-If you are interested in using git to manage (version control) projects, use Everyday GIT: \fIeveryday.html\fR as a guide to the minimum set of commands you need to know for day\-to\-day work\&. Most likely, that will get you started, and you can go a long way without knowing the low level details too much\&.
+If you are interested in using git to manage (version control) projects, use The Tutorial: \fItutorial.html\fR to get you started, and then Everyday GIT: \fIeveryday.html\fR as a guide to the minimum set of commands you need to know for day\-to\-day work\&. Most likely, that will get you started, and you can go a long way without knowing the low level details too much\&.
-The tutorial: \fItutorial.html\fR document covers how things internally work\&.
+The Core tutorial: \fIcore-tutorial.html\fR document covers how things internally work\&.
If you are migrating from CVS, cvs migration: \fIcvs-migration.html\fR document may be helpful after you finish the tutorial\&.
Provide content or type/size information for repository objects\&.
.TP
+\fBgit\-describe\fR(1)
+Show the most recent tag that is reachable from a commit\&.
+
+.TP
\fBgit\-diff\-index\fR(1)
Compares content and mode of blobs between the index and repository\&.
.TP
\fBgit\-receive\-pack\fR(1)
-Invoked by git\-send\-pack to receive what is pushed to it\&.
+Invoked by \fIgit\-send\-pack\fR to receive what is pushed to it\&.
.TP
\fBgit\-send\-pack\fR(1)
.TP
\fBgit\-upload\-pack\fR(1)
-Invoked by git\-clone\-pack and git\-fetch\-pack to push what are asked for\&.
+Invoked by \fIgit\-clone\-pack\fR and \fIgit\-fetch\-pack\fR to push what are asked for\&.
.SH "PORCELAIN-ISH COMMANDS"
Pack unpacked objects in a repository\&.
.TP
+\fBgit\-rerere\fR(1)
+Reuse recorded resolution of conflicted merges\&.
+
+.TP
\fBgit\-reset\fR(1)
Reset current HEAD to the specified state\&.
.TP
\fBgit\-shortlog\fR(1)
-Summarizes git log output\&.
+Summarizes \fIgit log\fR output\&.
.TP
\fBgit\-show\-branch\fR(1)
Send patch e\-mails out of "format\-patch \-\-mbox" output\&.
.TP
-\fBgit\-symbolic\-refs\fR(1)
+\fBgit\-symbolic\-ref\fR(1)
Read and modify symbolic refs\&.
.TP
Starting from 0\&.99\&.9 (actually mid 0\&.99\&.8\&.GIT), \&.git/config file is used to hold per\-repository configuration options\&. It is a simple text file modelled after \&.ini format familiar to some people\&. Here is an example:
-.IP
+.nf
#
# A '#' or ';' character indicates a comment\&.
#
name = "Junio C Hamano"
email = "junkio@twinsun\&.com"
+.fi
+
Various commands read from the configuration file and adjust their operation accordingly\&.
.TP
<tag>
-a valid tag name (i\&.e\&. the contents of $GIT_DIR/refs/tags/<tag>)\&.
+a valid tag \fIname\fR (i\&.e\&. the contents of $GIT_DIR/refs/tags/<tag>)\&.
.TP
<head>
-a valid head name (i\&.e\&. the contents of $GIT_DIR/refs/heads/<head>)\&.
+a valid head \fIname\fR (i\&.e\&. the contents of $GIT_DIR/refs/heads/<head>)\&.
.TP
<snap>
-a valid snapshot name (i\&.e\&. the contents of $GIT_DIR/refs/snap/<snap>)\&.
+a valid snapshot \fIname\fR (i\&.e\&. the contents of $GIT_DIR/refs/snap/<snap>)\&.
.SH "FILE/DIRECTORY STRUCTURE"
.SS "The git Repository"
-These environment variables apply to all core git commands\&. Nb: it is worth noting that they may be used/overridden by SCMS sitting above git so take care if using Cogito etc\&.
+These environment variables apply to \fIall\fR core git commands\&. Nb: it is worth noting that they may be used/overridden by SCMS sitting above git so take care if using Cogito etc\&.
.TP
-GIT_INDEX_FILE
+\fIGIT_INDEX_FILE\fR
This environment allows the specification of an alternate index file\&. If not specified, the default of $GIT_DIR/index is used\&.
.TP
-GIT_OBJECT_DIRECTORY
+\fIGIT_OBJECT_DIRECTORY\fR
If the object storage directory is specified via this environment variable then the sha1 directories are created underneath \- otherwise the default $GIT_DIR/objects directory is used\&.
.TP
-GIT_ALTERNATE_OBJECT_DIRECTORIES
+\fIGIT_ALTERNATE_OBJECT_DIRECTORIES\fR
Due to the immutable nature of git objects, old objects can be archived into shared, read\-only directories\&. This variable specifies a ":" separated list of git object directories which can be used to search for git objects\&. New objects will not be written to these directories\&.
.TP
-GIT_DIR
-If the GIT_DIR environment variable is set then it specifies a path to use instead of the default \&.git for the base of the repository\&.
+\fIGIT_DIR\fR
+If the \fIGIT_DIR\fR environment variable is set then it specifies a path to use instead of the default \&.git for the base of the repository\&.
.SS "git Commits"
.TP
-GIT_AUTHOR_NAME, GIT_AUTHOR_EMAIL, GIT_AUTHOR_DATE, GIT_COMMITTER_NAME, GIT_COMMITTER_EMAIL,
+\fIGIT_AUTHOR_NAME\fR, \fIGIT_AUTHOR_EMAIL\fR, \fIGIT_AUTHOR_DATE\fR, \fIGIT_COMMITTER_NAME\fR, \fIGIT_COMMITTER_EMAIL\fR
see \fBgit\-commit\-tree\fR(1)
.SS "git Diffs"
.TP
-GIT_DIFF_OPTS, GIT_EXTERNAL_DIFF,
+\fIGIT_DIFF_OPTS\fR, \fIGIT_EXTERNAL_DIFF\fR
see the "generating patches" section in : \fBgit\-diff\-index\fR(1); \fBgit\-diff\-files\fR(1); \fBgit\-diff\-tree\fR(1)
.SH "DISCUSSION"
.LP
-This is a stupid (but extremely fast) directory content manager\&. It doesn't do a whole lot, but what it does do is track directory contents efficiently\&.
+This is a stupid (but extremely fast) directory content manager\&. It doesn't do a whole lot, but what it \fIdoes\fR do is track directory contents efficiently\&.
There are two object abstractions: the "object database", and the "current directory cache" aka "index"\&.
A "tag" object symbolically identifies and can be used to sign other objects\&. It contains the identifier and type of another object, a symbolic name (of course!) and, optionally, a signature\&.
-Regardless of object type, all objects share the following characteristics: they are all deflated with zlib, and have a header that not only specifies their type, but also provides size information about the data in the object\&. It's worth noting that the SHA1 hash that is used to name the object is the hash of the original data plus this header, so sha1sum file does not match the object name for file\&. (Historical note: in the dawn of the age of git the hash was the sha1 of the compressed object\&.)
+Regardless of object type, all objects share the following characteristics: they are all deflated with zlib, and have a header that not only specifies their type, but also provides size information about the data in the object\&. It's worth noting that the SHA1 hash that is used to name the object is the hash of the original data plus this header, so sha1sum \fIfile\fR does not match the object name for \fIfile\fR\&. (Historical note: in the dawn of the age of git the hash was the sha1 of the \fIcompressed\fR object\&.)
As a result, the general consistency of an object can always be tested independently of the contents or the type of the object: all objects can be validated by verifying that (a) their hashes match the content of the file and (b) the object successfully inflates to a stream of bytes that forms a sequence of <ascii type without space> + <space> + <ascii decimal size> + <byte\\0> + <binary object data>\&.
.SS "Blob Object"
-A "blob" object is nothing but a binary blob of data, and doesn't refer to anything else\&. There is no signature or any other verification of the data, so while the object is consistent (it is indexed by its sha1 hash, so the data itself is certainly correct), it has absolutely no other attributes\&. No name associations, no permissions\&. It is purely a blob of data (i\&.e\&. normally "file contents")\&.
+A "blob" object is nothing but a binary blob of data, and doesn't refer to anything else\&. There is no signature or any other verification of the data, so while the object is consistent (it \fIis\fR indexed by its sha1 hash, so the data itself is certainly correct), it has absolutely no other attributes\&. No name associations, no permissions\&. It is purely a blob of data (i\&.e\&. normally "file contents")\&.
In particular, since the blob is entirely defined by its data, if two files in a directory tree (or in multiple different versions of the repository) have the same contents, they will share the same blob object\&. The object is totally independent of its location in the directory tree, and renaming a file does not change the object that file is associated with in any way\&.
For that reason a "tree" object is just a pure data abstraction: it has no history, no signatures, no verification of validity, except that since the contents are again protected by the hash itself, we can trust that the tree is immutable and its contents never change\&.
-So you can trust the contents of a tree to be valid, the same way you can trust the contents of a blob, but you don't know where those contents came from\&.
+So you can trust the contents of a tree to be valid, the same way you can trust the contents of a blob, but you don't know where those contents \fIcame\fR from\&.
Side note on trees: since a "tree" object is a sorted list of "filename+content", you can create a diff between two trees without actually having to unpack two trees\&. Just ignore all common parts, and your diff will look right\&. In other words, you can effectively (and efficiently) tell the difference between any two random trees by O(n) where "n" is the size of the difference, rather than the size of the tree\&.
.SS "Trust"
-An aside on the notion of "trust"\&. Trust is really outside the scope of "git", but it's worth noting a few things\&. First off, since everything is hashed with SHA1, you can trust that an object is intact and has not been messed with by external sources\&. So the name of an object uniquely identifies a known state \- just not a state that you may want to trust\&.
+An aside on the notion of "trust"\&. Trust is really outside the scope of "git", but it's worth noting a few things\&. First off, since everything is hashed with SHA1, you \fIcan\fR trust that an object is intact and has not been messed with by external sources\&. So the name of an object uniquely identifies a known state \- just not a state that you may want to trust\&.
Furthermore, since the SHA1 signature of a commit refers to the SHA1 signatures of the tree it is associated with and the signatures of the parent, a single named commit specifies uniquely a whole set of history, with full contents\&. You can't later fake any step of the way once you have the name of a commit\&.
-So to introduce some real trust in the system, the only thing you need to do is to digitally sign just one special note, which includes the name of a top\-level commit\&. Your digital signature shows others that you trust that commit, and the immutability of the history of commits tells others that they can trust the whole history\&.
+So to introduce some real trust in the system, the only thing you need to do is to digitally sign just \fIone\fR special note, which includes the name of a top\-level commit\&. Your digital signature shows others that you trust that commit, and the immutability of the history of commits tells others that they can trust the whole history\&.
In other words, you can easily validate a whole archive by just sending out a single email that tells the people the name (SHA1 hash) of the top commit, and digitally sign that email using something like GPG/PGP\&.
The index is a simple binary file, which contains an efficient representation of a virtual directory content at some random time\&. It does so by a simple array that associates a set of names, dates, permissions and content (aka "blob") objects together\&. The cache is always kept ordered by name, and names are unique (with a few very specific rules) at any point in time, but the cache has no long\-term meaning, and can be partially updated at any time\&.
-In particular, the index certainly does not need to be consistent with the current directory contents (in fact, most operations will depend on different ways to make the index not be consistent with the directory hierarchy), but it has three very important attributes:
+In particular, the index certainly does not need to be consistent with the current directory contents (in fact, most operations will depend on different ways to make the index \fInot\fR be consistent with the directory hierarchy), but it has three very important attributes:
-(a) it can re\-generate the full state it caches (not just the directory structure: it contains pointers to the "blob" objects so that it can regenerate the data too)
+\fI(a) it can re\-generate the full state it caches (not just the directory structure: it contains pointers to the "blob" objects so that it can regenerate the data too)\fR
As a special case, there is a clear and unambiguous one\-way mapping from a current directory cache to a "tree object", which can be efficiently created from just the current directory cache without actually looking at any other data\&. So a directory cache at any one time uniquely specifies one and only one "tree" object (but has additional data to make it easy to match up that tree object with what has happened in the directory)
-(b) it has efficient methods for finding inconsistencies between that cached state ("tree object waiting to be instantiated") and the current state\&.
+\fI(b) it has efficient methods for finding inconsistencies between that cached state ("tree object waiting to be instantiated") and the current state\&.\fR
-(c) it can additionally efficiently represent information about merge conflicts between different tree objects, allowing each pathname to be associated with sufficient information about the trees involved that you can create a three\-way merge between them\&.
+\fI(c) it can additionally efficiently represent information about merge conflicts between different tree objects, allowing each pathname to be associated with sufficient information about the trees involved that you can create a three\-way merge between them\&.\fR
Those are the three ONLY things that the directory cache does\&. It's a cache, and the normal operation is to re\-generate it completely from a known tree object, or update/compare it with a live tree that is being developed\&. If you blow the directory cache away entirely, you generally haven't lost any information as long as you have the name of the tree that it described\&.
.SH "THE WORKFLOW"
-Generally, all "git" operations work on the index file\&. Some operations work purely on the index file (showing the current state of the index), but most operations move data to and from the index file\&. Either from the database or from the working directory\&. Thus there are four main combinations:
+Generally, all "git" operations work on the index file\&. Some operations work \fIpurely\fR on the index file (showing the current state of the index), but most operations move data to and from the index file\&. Either from the database or from the working directory\&. Thus there are four main combinations:
.SS "1) working directory -> index"
To tell git that yes, you really do realize that certain files no longer exist, or that new files should be added, you should use the \-\-remove and \-\-add flags respectively\&.
-NOTE! A \-\-remove flag does not mean that subsequent filenames will necessarily be removed: if the files still exist in your directory structure, the index will be updated with their new status, not removed\&. The only thing \-\-remove means is that update\-cache will be considering a removed file to be a valid thing, and if the file really does not exist any more, it will update the index accordingly\&.
+NOTE! A \-\-remove flag does \fInot\fR mean that subsequent filenames will necessarily be removed: if the files still exist in your directory structure, the index will be updated with their new status, not removed\&. The only thing \-\-remove means is that update\-cache will be considering a removed file to be a valid thing, and if the file really does not exist any more, it will update the index accordingly\&.
-As a special case, you can also do git\-update\-index \-\-refresh, which will refresh the "stat" information of each index to match the current stat information\&. It will not update the object status itself, and it will only update the fields that are used to quickly test whether an object still matches its old backing store object\&.
+As a special case, you can also do git\-update\-index \-\-refresh, which will refresh the "stat" information of each index to match the current stat information\&. It will \fInot\fR update the object status itself, and it will only update the fields that are used to quickly test whether an object still matches its old backing store object\&.
.SS "2) index -> object database"
.fi
-and your index file will now be equivalent to the tree that you saved earlier\&. However, that is only your index file: your working directory contents have not been modified\&.
+and your index file will now be equivalent to the tree that you saved earlier\&. However, that is only your \fIindex\fR file: your working directory contents have not been modified\&.
.SS "4) index -> working directory"
or, if you want to check out all of the index, use \-a\&.
-NOTE! git\-checkout\-index normally refuses to overwrite old files, so if you have an old version of the tree already checked out, you will need to use the "\-f" flag (before the "\-a" flag or the filename) to force the checkout\&.
+NOTE! git\-checkout\-index normally refuses to overwrite old files, so if you have an old version of the tree already checked out, you will need to use the "\-f" flag (\fIbefore\fR the "\-a" flag or the filename) to \fIforce\fR the checkout\&.
Finally, there are a few odds and ends which are not purely moving from one representation to the other:
Here is an ASCII art by Jon Loeliger that illustrates how various pieces fit together\&.
-.IP
+.nf
commit\-tree
commit obj
| Directory |
+\-\-\-\-\-\-\-\-\-\-\-+
+.fi
+
.SS "6) Examining the data"
.SS "8) Merging multiple trees, continued"
-Sadly, many merges aren't trivial\&. If there are files that have been added\&.moved or removed, or if both branches have modified the same file, you will be left with an index tree that contains "merge entries" in it\&. Such an index tree can NOT be written out to a tree object, and you will have to resolve any such merge clashes using other tools before you can write out the result\&.
+Sadly, many merges aren't trivial\&. If there are files that have been added\&.moved or removed, or if both branches have modified the same file, you will be left with an index tree that contains "merge entries" in it\&. Such an index tree can \fINOT\fR be written out to a tree object, and you will have to resolve any such merge clashes using other tools before you can write out the result\&.
You can examine such index state with git\-ls\-files \-\-unmerged command\&. An example:
-.IP
+.nf
$ git\-read\-tree \-m $orig HEAD $target
$ git\-ls\-files \-\-unmerged
100644 263414f423d0e4d70dae8fe53fa34614ff3e2860 1 hello\&.c
100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 2 hello\&.c
100644 cc44c73eb783565da5831b4d820c962954019b69 3 hello\&.c
+.fi
-Each line of the git\-ls\-files \-\-unmerged output begins with the blob mode bits, blob SHA1, stage number, and the filename\&. The stage number is git's way to say which tree it came from: stage 1 corresponds to $orig tree, stage 2 HEAD tree, and stage3 $target tree\&.
+
+Each line of the git\-ls\-files \-\-unmerged output begins with the blob mode bits, blob SHA1, \fIstage number\fR, and the filename\&. The \fIstage number\fR is git's way to say which tree it came from: stage 1 corresponds to $orig tree, stage 2 HEAD tree, and stage3 $target tree\&.
Earlier we said that trivial merges are done inside git\-read\-tree \-m\&. For example, if the file did not change from $orig to HEAD nor $target, or if the file changed from $orig to HEAD and $orig to $target the same way, obviously the final outcome is what is in HEAD\&. What the above example shows is that file hello\&.c was changed from $orig to HEAD and $orig to $target in a different way\&. You could resolve this by running your favorite 3\-way merge program, e\&.g\&. diff3 or merge, on the blob objects from these three stages yourself, like this:
-.IP
+.nf
$ git\-cat\-file blob 263414f\&.\&.\&. >hello\&.c~1
$ git\-cat\-file blob 06fa6a2\&.\&.\&. >hello\&.c~2
$ git\-cat\-file blob cc44c73\&.\&.\&. >hello\&.c~3
$ merge hello\&.c~2 hello\&.c~1 hello\&.c~3
+.fi
+
This would leave the merge result in hello\&.c~2 file, along with conflict markers if there are conflicts\&. After verifying the merge result makes sense, you can tell git what the final merge result for this file is by:
projects / git.git / blobdiff