.SH "SYNOPSIS"
.nf
-git\-commit [\-a] [\-s] [\-v] [(\-c | \-C) <commit> | \-F <file> | \-m <msg>]
- [\-e] [\-\-] <file>...
+\fIgit\-commit\fR [\-a] [\-i] [\-s] [\-v] [(\-c | \-C) <commit> | \-F <file> | \-m <msg>]
+ [\-e] [\-\-author <author>] [\-\-] <file>...
.fi
.SH "DESCRIPTION"
-Updates the index file for given paths, or all modified files if \-a is specified, and makes a commit object\&. The command VISUAL and EDITOR environment variables to edit the commit log message\&.
+Updates the index file for given paths, or all modified files if \fI\-a\fR is specified, and makes a commit object\&. The command VISUAL and EDITOR environment variables to edit the commit log message\&.
This command can run commit\-msg, pre\-commit, and post\-commit hooks\&. See hooks: \fIhooks.html\fR for more information\&.
.TP
\-c or \-C <commit>
-Take existing commit object, and reuse the log message and the authorship information (including the timestamp) when creating the commit\&. With \-C, the editor is not invoked; with \-c the user can further edit the commit message\&.
+Take existing commit object, and reuse the log message and the authorship information (including the timestamp) when creating the commit\&. With \fI\-C\fR, the editor is not invoked; with \fI\-c\fR the user can further edit the commit message\&.
.TP
\-F <file>
-Take the commit message from the given file\&. Use \- to read the message from the standard input\&.
+Take the commit message from the given file\&. Use \fI\-\fR to read the message from the standard input\&.
+
+.TP
+\-\-author <author>
+Override the author name used in the commit\&. Use A U Thor <author@example\&.com> format\&.
.TP
\-m <msg>
.TP
\-v|\-\-verify
-Look for suspicious lines the commit introduces, and abort committing if there is one\&. The definition of suspicious lines is currently the lines that has trailing whitespaces, and the lines whose indentation has a SP character immediately followed by a TAB character\&. This is the default\&.
+Look for suspicious lines the commit introduces, and abort committing if there is one\&. The definition of \fIsuspicious lines\fR is currently the lines that has trailing whitespaces, and the lines whose indentation has a SP character immediately followed by a TAB character\&. This is the default\&.
.TP
\-n|\-\-no\-verify
\-e|\-\-edit
The message taken from file with \-F, command line with \-m, and from file with \-C are usually used as the commit log message unmodified\&. This option lets you further edit the message taken from these sources\&.
+.TP
+\-i|\-\-include
+Instead of committing only the files specified on the command line, update them in the index file and then commit the whole index\&. This is the traditional behaviour\&.
+
.TP
--
Do not interpret any more arguments as options\&.
.TP
<file>...
-Update specified paths in the index file before committing\&.
+Commit only the files specified on the command line\&. This format cannot be used during a merge, nor when the index and the latest commit does not match on the specified paths to avoid confusion\&.
If you make a commit and then found a mistake immediately after that, you can recover from it with \fBgit\-reset\fR(1)\&.
+.SH "DISCUSSION"
+
+
+git commit without _any_ parameter commits the tree structure recorded by the current index file\&. This is a whole\-tree commit even the command is invoked from a subdirectory\&.
+
+
+git commit \-\-include paths... is equivalent to
+
+.nf
+git update\-index \-\-remove paths\&.\&.\&.
+git commit
+.fi
+
+
+That is, update the specified paths to the index and then commit the whole tree\&.
+
+
+git commit paths... largely bypasses the index file and commits only the changes made to the specified paths\&. It has however several safety valves to prevent confusion\&.
+
+.TP 3
+1.
+It refuses to run during a merge (i\&.e\&. when $GIT_DIR/MERGE_HEAD exists), and reminds trained git users that the traditional semantics now needs \-i flag\&.
+.TP
+2.
+It refuses to run if named paths... are different in HEAD and the index (ditto about reminding)\&. Added paths are OK\&. This is because an earlier git diff (not git diff HEAD) would have shown the differences since the last git update\-index paths... to the user, and an inexperienced user may mistakenly think that the changes between the index and the HEAD (i\&.e\&. earlier changes made before the last git update\-index paths... was done) are not being committed\&.
+.TP
+3.
+It reads HEAD commit into a temporary index file, updates the specified paths... and makes a commit\&. At the same time, the real index file is also updated with the same paths...\&.
+.LP
+
+
+git commit \-\-all updates the index file with _all_ changes to the working tree, and makes a whole\-tree commit, regardless of which subdirectory the command is invoked in\&.
+
.SH "AUTHOR"
.SH "SYNOPSIS"
-git\-fetch <options> <repository> <refspec>...
+\fIgit\-fetch\fR <options> <repository> <refspec>...
.SH "DESCRIPTION"
.TP
\-\-upload\-pack <upload\-pack>
-When given, and the repository to fetch from is handled by git\-fetch\-pack, \-\-exec=<upload\-pack> is passed to the command to specify non\-default path for the command run on the other end\&.
+When given, and the repository to fetch from is handled by \fIgit\-fetch\-pack\fR, \fI\-\-exec=<upload\-pack>\fR is passed to the command to specify non\-default path for the command run on the other end\&.
.TP
\-f, \-\-force
.TP
<repository>
-The "remote" repository that is the source of a fetch or pull operation, or the destination of a push operation\&. One of the following notations can be used to name the remote repository:
+The "remote" repository that is the source of a fetch or pull operation\&. See the section GIT URLS below\&.
+.TP
+<refspec>
+The canonical format of a <refspec> parameter is +?<src>:<dst>; that is, an optional plus +, followed by the source ref, followed by a colon :, followed by the destination ref\&.
+
+The remote ref that matches <src> is fetched, and if <dst> is not empty string, the local ref that matches it is fast forwarded using <src>\&. Again, if the optional plus + is used, the local ref is updated even if it does not result in a fast forward update\&.
-.IP
+
+.RS
+.Sh "Note"
+If the remote branch from which you want to pull is modified in non\-linear ways such as being rewound and rebased frequently, then a pull will attempt a merge with an older version of itself, likely conflict, and fail\&. It is under these conditions that you would want to use the + sign to indicate non\-fast\-forward updates will be needed\&. There is currently no easy way to determine or declare that a branch will be made available in a repository with this behavior; the pulling user simply must know this is the expected usage pattern for a branch\&.
+
+.RE
+
+.RS
+.Sh "Note"
+You never do your own development on branches that appear on the right hand side of a <refspec> colon on Pull: lines; they are to be updated by git\-fetch\&. If you intend to do development derived from a remote branch B, have a Pull: line to track it (i\&.e\&. Pull: B:remote\-B), and have a separate branch my\-B to do your development on top of it\&. The latter is created by git branch my\-B remote\-B (or its equivalent git checkout \-b my\-B remote\-B)\&. Run git fetch to keep track of the progress of the remote side, and when you see something new on the remote branch, merge it into your development branch with git pull \&. remote\-B, while you are on my\-B branch\&. The common Pull: master:origin mapping of a remote master branch to a local origin branch, which is then merged to a local development branch, again typically named master, is made when you run git clone for you to follow this pattern\&.
+
+.RE
+
+.RS
+.Sh "Note"
+There is a difference between listing multiple <refspec> directly on git\-pull command line and having multiple Pull: <refspec> lines for a <repository> and running git\-pull command without any explicit <refspec> parameters\&. <refspec> listed explicitly on the command line are always merged into the current branch after fetching\&. In other words, if you list more than one remote refs, you would be making an Octopus\&. While git\-pull run without any explicit <refspec> parameter takes default <refspec>s from Pull: lines, it merges only the first <refspec> found into the current branch, after fetching all the remote refs\&. This is because making an Octopus from remote refs is rarely done, while keeping track of multiple remote heads in one\-go by fetching more than one is often useful\&.
+
+.RE
+Some short\-cut notations are also supported\&.
.RS
+.TP 3
+\(bu
+ tag <tag> means the same as refs/tags/<tag>:refs/tags/<tag>; it requests fetching everything up to the given tag\&.
+.TP
+\(bu
+A parameter <ref> without a colon is equivalent to <ref>: when pulling/fetching, so it merges <ref> into the current branch without storing the remote branch anywhere locally
+.LP
+.RE
+.IP
+
+.SH "GIT URLS"
+
+
+One of the following notations can be used to name the remote repository:
+
+.IP
+
.TP 3
\(bu
rsync://host\&.xz/path/to/repo\&.git/
\(bu
ssh://host\&.xz/~/path/to/repo\&.git
.LP
-.RE
-.IP
-SSH Is the default transport protocol and also supports an scp\-like syntax\&. Both syntaxes support username expansion, as does the native git protocol\&. The following three are identical to the last three above, respectively:
+SSH Is the default transport protocol and also supports an scp\-like syntax\&. Both syntaxes support username expansion, as does the native git protocol\&. The following three are identical to the last three above, respectively:
+
.IP
-.RS
.TP 3
\(bu
host\&.xz:/path/to/repo\&.git/
\(bu
host\&.xz:path/to/repo\&.git
.LP
-.RE
-.IP
-To sync with a local directory, use:
+To sync with a local directory, use:
+
.IP
-.RS
.TP 3
\(bu
/path/to/repo\&.git/
.LP
-.RE
-.IP
-In addition to the above, as a short\-hand, the name of a file in $GIT_DIR/remotes directory can be given; the named file should be in the following format:
+.SH "REMOTES"
+
+
+In addition to the above, as a short\-hand, the name of a file in $GIT_DIR/remotes directory can be given; the named file should be in the following format:
.nf
URL: one of the above URL format
Push: <refspec>
Pull: <refspec>
.fi
-When such a short\-hand is specified in place of <repository> without <refspec> parameters on the command line, <refspec> specified on Push: lines or Pull: lines are used for git\-push and git\-fetch/git\-pull, respectively\&. Multiple Push: and and Pull: lines may be specified for additional branch mappings\&.
-The name of a file in $GIT_DIR/branches directory can be specified as an older notation short\-hand; the named file should contain a single line, a URL in one of the above formats, optionally followed by a hash # and the name of remote head (URL fragment notation)\&. $GIT_DIR/branches/<remote> file that stores a <url> without the fragment is equivalent to have this in the corresponding file in the $GIT_DIR/remotes/ directory\&.
+Then such a short\-hand is specified in place of <repository> without <refspec> parameters on the command line, <refspec> specified on Push: lines or Pull: lines are used for git\-push and git\-fetch/git\-pull, respectively\&. Multiple Push: and and Pull: lines may be specified for additional branch mappings\&.
+
+
+The name of a file in $GIT_DIR/branches directory can be specified as an older notation short\-hand; the named file should contain a single line, a URL in one of the above formats, optionally followed by a hash # and the name of remote head (URL fragment notation)\&. $GIT_DIR/branches/<remote> file that stores a <url> without the fragment is equivalent to have this in the corresponding file in the $GIT_DIR/remotes/ directory\&.
.nf
URL: <url>
Pull: refs/heads/master:<remote>
.fi
+
+
while having <url>#<head> is equivalent to
.nf
Pull: refs/heads/<head>:<remote>
.fi
-.TP
-<refspec>
-The canonical format of a <refspec> parameter is +?<src>:<dst>; that is, an optional plus +, followed by the source ref, followed by a colon :, followed by the destination ref\&.
-
-When used in git\-push, the <src> side can be an arbitrary "SHA1 expression" that can be used as an argument to git\-cat\-file \-t\&. E\&.g\&. master~4 (push four parents before the current master head)\&.
-
-For git\-push, the local ref that matches <src> is used to fast forward the remote ref that matches <dst>\&. If the optional plus + is used, the remote ref is updated even if it does not result in a fast forward update\&.
-
-For git\-fetch and git\-pull, the remote ref that matches <src> is fetched, and if <dst> is not empty string, the local ref that matches it is fast forwarded using <src>\&. Again, if the optional plus + is used, the local ref is updated even if it does not result in a fast forward update\&.
-
-
-.RS
-.Sh "Note"
-If the remote branch from which you want to pull is modified in non\-linear ways such as being rewound and rebased frequently, then a pull will attempt a merge with an older version of itself, likely conflict, and fail\&. It is under these conditions that you would want to use the + sign to indicate non\-fast\-forward updates will be needed\&. There is currently no easy way to determine or declare that a branch will be made available in a repository with this behavior; the pulling user simply must know this is the expected usage pattern for a branch\&.
-
-.RE
-
-.RS
-.Sh "Note"
-You never do your own development on branches that appear on the right hand side of a <refspec> colon on Pull: lines; they are to be updated by git\-fetch\&. If you intend to do development derived from a remote branch B, have a Pull: line to track it (i\&.e\&. Pull: B:remote\-B), and have a separate branch my\-B to do your development on top of it\&. The latter is created by git branch my\-B remote\-B (or its equivalent git checkout \-b my\-B remote\-B)\&. Run git fetch to keep track of the progress of the remote side, and when you see something new on the remote branch, merge it into your development branch with git pull \&. remote\-B, while you are on my\-B branch\&. The common Pull: master:origin mapping of a remote master branch to a local origin branch, which is then merged to a local development branch, again typically named master, is made when you run git clone for you to follow this pattern\&.
-
-.RE
-
-.RS
-.Sh "Note"
-There is a difference between listing multiple <refspec> directly on git\-pull command line and having multiple Pull: <refspec> lines for a <repository> and running git\-pull command without any explicit <refspec> parameters\&. <refspec> listed explicitly on the command line are always merged into the current branch after fetching\&. In other words, if you list more than one remote refs, you would be making an Octopus\&. While git\-pull run without any explicit <refspec> parameter takes default <refspec>s from Pull: lines, it merges only the first <refspec> found into the current branch, after fetching all the remote refs\&. This is because making an Octopus from remote refs is rarely done, while keeping track of multiple remote heads in one\-go by fetching more than one is often useful\&.
-
-.RE
-Some short\-cut notations are also supported\&.
-
-.RS
-.TP 3
-\(bu
- tag <tag> means the same as refs/tags/<tag>:refs/tags/<tag>; used with pull or fetch, it requests fetching everything up to the given tag\&.
-.TP
-\(bu
-A parameter <ref> without a colon is equivalent to <ref>: when pulling/fetching, and <ref>:<ref> when pushing\&. That is, do not store it locally if fetching, and update the same name if pushing\&.
-.LP
-.RE
-.IP
-
.SH "SEE ALSO"
.SH "SYNOPSIS"
-git\-pull <options> <repository> <refspec>...
+\fIgit\-pull\fR <options> <repository> <refspec>...
.SH "DESCRIPTION"
.TP
\-\-upload\-pack <upload\-pack>
-When given, and the repository to fetch from is handled by git\-fetch\-pack, \-\-exec=<upload\-pack> is passed to the command to specify non\-default path for the command run on the other end\&.
+When given, and the repository to fetch from is handled by \fIgit\-fetch\-pack\fR, \fI\-\-exec=<upload\-pack>\fR is passed to the command to specify non\-default path for the command run on the other end\&.
.TP
\-f, \-\-force
.TP
<repository>
-The "remote" repository that is the source of a fetch or pull operation, or the destination of a push operation\&. One of the following notations can be used to name the remote repository:
+The "remote" repository that is the source of a fetch or pull operation\&. See the section GIT URLS below\&.
+.TP
+<refspec>
+The canonical format of a <refspec> parameter is +?<src>:<dst>; that is, an optional plus +, followed by the source ref, followed by a colon :, followed by the destination ref\&.
+
+The remote ref that matches <src> is fetched, and if <dst> is not empty string, the local ref that matches it is fast forwarded using <src>\&. Again, if the optional plus + is used, the local ref is updated even if it does not result in a fast forward update\&.
-.IP
+
+.RS
+.Sh "Note"
+If the remote branch from which you want to pull is modified in non\-linear ways such as being rewound and rebased frequently, then a pull will attempt a merge with an older version of itself, likely conflict, and fail\&. It is under these conditions that you would want to use the + sign to indicate non\-fast\-forward updates will be needed\&. There is currently no easy way to determine or declare that a branch will be made available in a repository with this behavior; the pulling user simply must know this is the expected usage pattern for a branch\&.
+
+.RE
+
+.RS
+.Sh "Note"
+You never do your own development on branches that appear on the right hand side of a <refspec> colon on Pull: lines; they are to be updated by git\-fetch\&. If you intend to do development derived from a remote branch B, have a Pull: line to track it (i\&.e\&. Pull: B:remote\-B), and have a separate branch my\-B to do your development on top of it\&. The latter is created by git branch my\-B remote\-B (or its equivalent git checkout \-b my\-B remote\-B)\&. Run git fetch to keep track of the progress of the remote side, and when you see something new on the remote branch, merge it into your development branch with git pull \&. remote\-B, while you are on my\-B branch\&. The common Pull: master:origin mapping of a remote master branch to a local origin branch, which is then merged to a local development branch, again typically named master, is made when you run git clone for you to follow this pattern\&.
+
+.RE
+
+.RS
+.Sh "Note"
+There is a difference between listing multiple <refspec> directly on git\-pull command line and having multiple Pull: <refspec> lines for a <repository> and running git\-pull command without any explicit <refspec> parameters\&. <refspec> listed explicitly on the command line are always merged into the current branch after fetching\&. In other words, if you list more than one remote refs, you would be making an Octopus\&. While git\-pull run without any explicit <refspec> parameter takes default <refspec>s from Pull: lines, it merges only the first <refspec> found into the current branch, after fetching all the remote refs\&. This is because making an Octopus from remote refs is rarely done, while keeping track of multiple remote heads in one\-go by fetching more than one is often useful\&.
+
+.RE
+Some short\-cut notations are also supported\&.
.RS
+.TP 3
+\(bu
+ tag <tag> means the same as refs/tags/<tag>:refs/tags/<tag>; it requests fetching everything up to the given tag\&.
+.TP
+\(bu
+A parameter <ref> without a colon is equivalent to <ref>: when pulling/fetching, so it merges <ref> into the current branch without storing the remote branch anywhere locally
+.LP
+.RE
+.IP
+
+.SH "GIT URLS"
+
+
+One of the following notations can be used to name the remote repository:
+
+.IP
+
.TP 3
\(bu
rsync://host\&.xz/path/to/repo\&.git/
\(bu
ssh://host\&.xz/~/path/to/repo\&.git
.LP
-.RE
-.IP
-SSH Is the default transport protocol and also supports an scp\-like syntax\&. Both syntaxes support username expansion, as does the native git protocol\&. The following three are identical to the last three above, respectively:
+SSH Is the default transport protocol and also supports an scp\-like syntax\&. Both syntaxes support username expansion, as does the native git protocol\&. The following three are identical to the last three above, respectively:
+
.IP
-.RS
.TP 3
\(bu
host\&.xz:/path/to/repo\&.git/
\(bu
host\&.xz:path/to/repo\&.git
.LP
-.RE
-.IP
-To sync with a local directory, use:
+To sync with a local directory, use:
+
.IP
-.RS
.TP 3
\(bu
/path/to/repo\&.git/
.LP
-.RE
-.IP
-In addition to the above, as a short\-hand, the name of a file in $GIT_DIR/remotes directory can be given; the named file should be in the following format:
+.SH "REMOTES"
+
+
+In addition to the above, as a short\-hand, the name of a file in $GIT_DIR/remotes directory can be given; the named file should be in the following format:
.nf
URL: one of the above URL format
Push: <refspec>
Pull: <refspec>
.fi
-When such a short\-hand is specified in place of <repository> without <refspec> parameters on the command line, <refspec> specified on Push: lines or Pull: lines are used for git\-push and git\-fetch/git\-pull, respectively\&. Multiple Push: and and Pull: lines may be specified for additional branch mappings\&.
-The name of a file in $GIT_DIR/branches directory can be specified as an older notation short\-hand; the named file should contain a single line, a URL in one of the above formats, optionally followed by a hash # and the name of remote head (URL fragment notation)\&. $GIT_DIR/branches/<remote> file that stores a <url> without the fragment is equivalent to have this in the corresponding file in the $GIT_DIR/remotes/ directory\&.
+Then such a short\-hand is specified in place of <repository> without <refspec> parameters on the command line, <refspec> specified on Push: lines or Pull: lines are used for git\-push and git\-fetch/git\-pull, respectively\&. Multiple Push: and and Pull: lines may be specified for additional branch mappings\&.
+
+
+The name of a file in $GIT_DIR/branches directory can be specified as an older notation short\-hand; the named file should contain a single line, a URL in one of the above formats, optionally followed by a hash # and the name of remote head (URL fragment notation)\&. $GIT_DIR/branches/<remote> file that stores a <url> without the fragment is equivalent to have this in the corresponding file in the $GIT_DIR/remotes/ directory\&.
.nf
URL: <url>
Pull: refs/heads/master:<remote>
.fi
+
+
while having <url>#<head> is equivalent to
.nf
Pull: refs/heads/<head>:<remote>
.fi
-.TP
-<refspec>
-The canonical format of a <refspec> parameter is +?<src>:<dst>; that is, an optional plus +, followed by the source ref, followed by a colon :, followed by the destination ref\&.
-
-When used in git\-push, the <src> side can be an arbitrary "SHA1 expression" that can be used as an argument to git\-cat\-file \-t\&. E\&.g\&. master~4 (push four parents before the current master head)\&.
-
-For git\-push, the local ref that matches <src> is used to fast forward the remote ref that matches <dst>\&. If the optional plus + is used, the remote ref is updated even if it does not result in a fast forward update\&.
-
-For git\-fetch and git\-pull, the remote ref that matches <src> is fetched, and if <dst> is not empty string, the local ref that matches it is fast forwarded using <src>\&. Again, if the optional plus + is used, the local ref is updated even if it does not result in a fast forward update\&.
-
-
-.RS
-.Sh "Note"
-If the remote branch from which you want to pull is modified in non\-linear ways such as being rewound and rebased frequently, then a pull will attempt a merge with an older version of itself, likely conflict, and fail\&. It is under these conditions that you would want to use the + sign to indicate non\-fast\-forward updates will be needed\&. There is currently no easy way to determine or declare that a branch will be made available in a repository with this behavior; the pulling user simply must know this is the expected usage pattern for a branch\&.
-
-.RE
-
-.RS
-.Sh "Note"
-You never do your own development on branches that appear on the right hand side of a <refspec> colon on Pull: lines; they are to be updated by git\-fetch\&. If you intend to do development derived from a remote branch B, have a Pull: line to track it (i\&.e\&. Pull: B:remote\-B), and have a separate branch my\-B to do your development on top of it\&. The latter is created by git branch my\-B remote\-B (or its equivalent git checkout \-b my\-B remote\-B)\&. Run git fetch to keep track of the progress of the remote side, and when you see something new on the remote branch, merge it into your development branch with git pull \&. remote\-B, while you are on my\-B branch\&. The common Pull: master:origin mapping of a remote master branch to a local origin branch, which is then merged to a local development branch, again typically named master, is made when you run git clone for you to follow this pattern\&.
-
-.RE
-
-.RS
-.Sh "Note"
-There is a difference between listing multiple <refspec> directly on git\-pull command line and having multiple Pull: <refspec> lines for a <repository> and running git\-pull command without any explicit <refspec> parameters\&. <refspec> listed explicitly on the command line are always merged into the current branch after fetching\&. In other words, if you list more than one remote refs, you would be making an Octopus\&. While git\-pull run without any explicit <refspec> parameter takes default <refspec>s from Pull: lines, it merges only the first <refspec> found into the current branch, after fetching all the remote refs\&. This is because making an Octopus from remote refs is rarely done, while keeping track of multiple remote heads in one\-go by fetching more than one is often useful\&.
-
-.RE
-Some short\-cut notations are also supported\&.
-
-.RS
-.TP 3
-\(bu
- tag <tag> means the same as refs/tags/<tag>:refs/tags/<tag>; used with pull or fetch, it requests fetching everything up to the given tag\&.
-.TP
-\(bu
-A parameter <ref> without a colon is equivalent to <ref>: when pulling/fetching, and <ref>:<ref> when pushing\&. That is, do not store it locally if fetching, and update the same name if pushing\&.
-.LP
-.RE
-.IP
-
.SH "MERGE STRATEGIES"
.TP
.SH "SYNOPSIS"
-git\-push [\-\-all] [\-\-tags] [\-\-force] <repository> <refspec>...
+\fIgit\-push\fR [\-\-all] [\-\-tags] [\-\-force] <repository> <refspec>...
.SH "DESCRIPTION"
Updates remote refs using local refs, while sending objects necessary to complete the given refs\&.
-You can make "interesting" things to happen on the repository every time you push into it, by setting up hooks there\&. See documentation for \fBgit\-receive\-pack\fR(1)\&.
+You can make interesting things happen to a repository every time you push into it, by setting up \fIhooks\fR there\&. See documentation for \fBgit\-receive\-pack\fR(1)\&.
.SH "OPTIONS"
.TP
<repository>
-The "remote" repository that is the source of a fetch or pull operation, or the destination of a push operation\&. One of the following notations can be used to name the remote repository:
+The "remote" repository that is destination of a push operation\&. See the section GIT URLS below\&.
+.TP
+<refspec>
+The canonical format of a <refspec> parameter is +?<src>:<dst>; that is, an optional plus +, followed by the source ref, followed by a colon :, followed by the destination ref\&.
-.IP
+The <src> side can be an arbitrary "SHA1 expression" that can be used as an argument to git\-cat\-file \-t\&. E\&.g\&. master~4 (push four parents before the current master head)\&.
+
+The local ref that matches <src> is used to fast forward the remote ref that matches <dst>\&. If the optional plus + is used, the remote ref is updated even if it does not result in a fast forward update\&.
+
+Some short\-cut notations are also supported\&.
.RS
+.TP 3
+\(bu
+ tag <tag> means the same as refs/tags/<tag>:refs/tags/<tag>\&.
+.TP
+\(bu
+A parameter <ref> without a colon is equivalent to <ref>:<ref>, hence updates <ref> in the destination from <ref> in the source\&.
+.LP
+.RE
+.IP
+
+.TP
+\-\-all
+Instead of naming each ref to push, specifies that all refs be pushed\&.
+
+.TP
+\-\-tags
+All refs under $GIT_DIR/refs/tags are pushed, in addition to refspecs explicitly listed on the command line\&.
+
+.TP
+\-f, \-\-force
+Usually, the command refuses to update a remote ref that is not a descendent of the local ref used to overwrite it\&. This flag disables the check\&. This can cause the remote repository to lose commits; use it with care\&.
+
+.SH "GIT URLS"
+
+
+One of the following notations can be used to name the remote repository:
+
+.IP
+
.TP 3
\(bu
rsync://host\&.xz/path/to/repo\&.git/
\(bu
ssh://host\&.xz/~/path/to/repo\&.git
.LP
-.RE
-.IP
-SSH Is the default transport protocol and also supports an scp\-like syntax\&. Both syntaxes support username expansion, as does the native git protocol\&. The following three are identical to the last three above, respectively:
+SSH Is the default transport protocol and also supports an scp\-like syntax\&. Both syntaxes support username expansion, as does the native git protocol\&. The following three are identical to the last three above, respectively:
+
.IP
-.RS
.TP 3
\(bu
host\&.xz:/path/to/repo\&.git/
\(bu
host\&.xz:path/to/repo\&.git
.LP
-.RE
-.IP
-To sync with a local directory, use:
+To sync with a local directory, use:
+
.IP
-.RS
.TP 3
\(bu
/path/to/repo\&.git/
.LP
-.RE
-.IP
-In addition to the above, as a short\-hand, the name of a file in $GIT_DIR/remotes directory can be given; the named file should be in the following format:
+.SH "REMOTES"
+
+
+In addition to the above, as a short\-hand, the name of a file in $GIT_DIR/remotes directory can be given; the named file should be in the following format:
.nf
URL: one of the above URL format
Push: <refspec>
Pull: <refspec>
.fi
-When such a short\-hand is specified in place of <repository> without <refspec> parameters on the command line, <refspec> specified on Push: lines or Pull: lines are used for git\-push and git\-fetch/git\-pull, respectively\&. Multiple Push: and and Pull: lines may be specified for additional branch mappings\&.
-The name of a file in $GIT_DIR/branches directory can be specified as an older notation short\-hand; the named file should contain a single line, a URL in one of the above formats, optionally followed by a hash # and the name of remote head (URL fragment notation)\&. $GIT_DIR/branches/<remote> file that stores a <url> without the fragment is equivalent to have this in the corresponding file in the $GIT_DIR/remotes/ directory\&.
+
+Then such a short\-hand is specified in place of <repository> without <refspec> parameters on the command line, <refspec> specified on Push: lines or Pull: lines are used for git\-push and git\-fetch/git\-pull, respectively\&. Multiple Push: and and Pull: lines may be specified for additional branch mappings\&.
+The name of a file in $GIT_DIR/branches directory can be specified as an older notation short\-hand; the named file should contain a single line, a URL in one of the above formats, optionally followed by a hash # and the name of remote head (URL fragment notation)\&. $GIT_DIR/branches/<remote> file that stores a <url> without the fragment is equivalent to have this in the corresponding file in the $GIT_DIR/remotes/ directory\&.
+
.nf
URL: <url>
Pull: refs/heads/master:<remote>
.fi
+
+
while having <url>#<head> is equivalent to
.nf
Pull: refs/heads/<head>:<remote>
.fi
-.TP
-<refspec>
-The canonical format of a <refspec> parameter is +?<src>:<dst>; that is, an optional plus +, followed by the source ref, followed by a colon :, followed by the destination ref\&.
-
-When used in git\-push, the <src> side can be an arbitrary "SHA1 expression" that can be used as an argument to git\-cat\-file \-t\&. E\&.g\&. master~4 (push four parents before the current master head)\&.
-
-For git\-push, the local ref that matches <src> is used to fast forward the remote ref that matches <dst>\&. If the optional plus + is used, the remote ref is updated even if it does not result in a fast forward update\&.
-
-For git\-fetch and git\-pull, the remote ref that matches <src> is fetched, and if <dst> is not empty string, the local ref that matches it is fast forwarded using <src>\&. Again, if the optional plus + is used, the local ref is updated even if it does not result in a fast forward update\&.
-
-
-.RS
-.Sh "Note"
-If the remote branch from which you want to pull is modified in non\-linear ways such as being rewound and rebased frequently, then a pull will attempt a merge with an older version of itself, likely conflict, and fail\&. It is under these conditions that you would want to use the + sign to indicate non\-fast\-forward updates will be needed\&. There is currently no easy way to determine or declare that a branch will be made available in a repository with this behavior; the pulling user simply must know this is the expected usage pattern for a branch\&.
-
-.RE
-
-.RS
-.Sh "Note"
-You never do your own development on branches that appear on the right hand side of a <refspec> colon on Pull: lines; they are to be updated by git\-fetch\&. If you intend to do development derived from a remote branch B, have a Pull: line to track it (i\&.e\&. Pull: B:remote\-B), and have a separate branch my\-B to do your development on top of it\&. The latter is created by git branch my\-B remote\-B (or its equivalent git checkout \-b my\-B remote\-B)\&. Run git fetch to keep track of the progress of the remote side, and when you see something new on the remote branch, merge it into your development branch with git pull \&. remote\-B, while you are on my\-B branch\&. The common Pull: master:origin mapping of a remote master branch to a local origin branch, which is then merged to a local development branch, again typically named master, is made when you run git clone for you to follow this pattern\&.
-
-.RE
-
-.RS
-.Sh "Note"
-There is a difference between listing multiple <refspec> directly on git\-pull command line and having multiple Pull: <refspec> lines for a <repository> and running git\-pull command without any explicit <refspec> parameters\&. <refspec> listed explicitly on the command line are always merged into the current branch after fetching\&. In other words, if you list more than one remote refs, you would be making an Octopus\&. While git\-pull run without any explicit <refspec> parameter takes default <refspec>s from Pull: lines, it merges only the first <refspec> found into the current branch, after fetching all the remote refs\&. This is because making an Octopus from remote refs is rarely done, while keeping track of multiple remote heads in one\-go by fetching more than one is often useful\&.
-
-.RE
-Some short\-cut notations are also supported\&.
-
-.RS
-.TP 3
-\(bu
- tag <tag> means the same as refs/tags/<tag>:refs/tags/<tag>; used with pull or fetch, it requests fetching everything up to the given tag\&.
-.TP
-\(bu
-A parameter <ref> without a colon is equivalent to <ref>: when pulling/fetching, and <ref>:<ref> when pushing\&. That is, do not store it locally if fetching, and update the same name if pushing\&.
-.LP
-.RE
-.IP
-
-.TP
-\-\-all
-Instead of naming each ref to push, specifies all refs to be pushed\&.
-
-.TP
-\-\-tags
-All refs under $GIT_DIR/refs/tags are pushed, in addition to refspecs explicitly listed on the command line\&.
-
-.TP
-\-f, \-\-force
-Usually, the command refuses to update a remote ref that is not a descendent of the local ref used to overwrite it\&. This flag disables the check\&. This can cause the remote repository to lose commits; use it with care\&.
-
.SH "AUTHOR"
--- /dev/null
+.\"Generated by db2man.xsl. Don't modify this, modify the source.
+.de Sh \" Subsection
+.br
+.if t .Sp
+.ne 5
+.PP
+\fB\\$1\fR
+.PP
+..
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Ip \" List item
+.br
+.ie \\n(.$>=3 .ne \\$3
+.el .ne 3
+.IP "\\$1" \\$2
+..
+.TH "GIT-RERERE" 1 "" "" ""
+.SH NAME
+git-rerere \- Reuse recorded resolve
+.SH "SYNOPSIS"
+
+
+\fIgit\-rerere\fR
+
+.SH "DESCRIPTION"
+
+
+In a workflow that employs relatively long lived topic branches, the developer sometimes needs to resolve the same conflict over and over again until the topic branches are done (either merged to the "release" branch, or sent out and accepted upstream)\&.
+
+
+This command helps this process by recording conflicted automerge results and corresponding hand\-resolve results on the initial manual merge, and later by noticing the same automerge results and applying the previously recorded hand resolution\&.
+
+.RS
+.Sh "Note"
+
+
+You need to create $GIT_DIR/rr\-cache directory to enable this command\&.
+
+.RE
+
+.SH "DISCUSSION"
+
+
+When your topic branch modifies overlapping area that your master branch (or upstream) touched since your topic branch forked from it, you may want to test it with the latest master, even before your topic branch is ready to be pushed upstream:
+
+.IP
+ o\-\-\-*\-\-\-o topic
+ /
+ o\-\-\-o\-\-\-o\-\-\-*\-\-\-o\-\-\-o master
+
+For such a test, you need to merge master and topic somehow\&. One way to do it is to pull master into the topic branch:
+
+.IP
+ $ git checkout topic
+ $ git pull \&. master
+
+ o\-\-\-*\-\-\-o\-\-\-+ topic
+ / /
+ o\-\-\-o\-\-\-o\-\-\-*\-\-\-o\-\-\-o master
+
+The commits marked with * touch the same area in the same file; you need to resolve the conflicts when creating the commit marked with +\&. Then you can test the result to make sure your work\-in\-progress still works with what is in the latest master\&.
+
+
+After this test merge, there are two ways to continue your work on the topic\&. The easiest is to build on top of the test merge commit +, and when your work in the topic branch is finally ready, pull the topic branch into master, and/or ask the upstream to pull from you\&. By that time, however, the master or the upstream might have been advanced since the test merge +, in which case the final commit graph would look like this:
+
+.IP
+ $ git checkout topic
+ $ git pull \&. master
+ $ \&.\&.\&. work on both topic and master branches
+ $ git checkout master
+ $ git pull \&. topic
+
+ o\-\-\-*\-\-\-o\-\-\-+\-\-\-o\-\-\-o topic
+ / / \\
+ o\-\-\-o\-\-\-o\-\-\-*\-\-\-o\-\-\-o\-\-\-o\-\-\-o\-\-\-+ master
+
+When your topic branch is long\-lived, however, your topic branch would end up having many such "Merge from master" commits on it, which would unnecessarily clutter the development history\&. Readers of the Linux kernel mailing list may remember that Linus complained about such too frequent test merges when a subsystem maintainer asked to pull from a branch full of "useless merges"\&.
+
+
+As an alternative, to keep the topic branch clean of test merges, you could blow away the test merge, and keep building on top of the tip before the test merge:
+
+.IP
+ $ git checkout topic
+ $ git pull \&. master
+ $ git reset \-\-hard HEAD^ ;# rewind the test merge
+ $ \&.\&.\&. work on both topic and master branches
+ $ git checkout master
+ $ git pull \&. topic
+
+ o\-\-\-*\-\-\-o\-\-\-\-\-\-\-o\-\-\-o topic
+ / \\
+ o\-\-\-o\-\-\-o\-\-\-*\-\-\-o\-\-\-o\-\-\-o\-\-\-o\-\-\-+ master
+
+This would leave only one merge commit when your topic branch is finally ready and merged into the master branch\&. This merge would require you to resolve the conflict, introduced by the commits marked with *\&. However, often this conflict is the same conflict you resolved when you created the test merge you blew away\&. git\-rerere command helps you to resolve this final conflicted merge using the information from your earlier hand resolve\&.
+
+
+Running git\-rerere command immediately after a conflicted automerge records the conflicted working tree files, with the usual conflict markers <<<<<<<, =======, and >>>>>>> in them\&. Later, after you are done resolving the conflicts, running git\-rerere again records the resolved state of these files\&. Suppose you did this when you created the test merge of master into the topic branch\&.
+
+
+Next time, running git\-rerere after seeing a conflicted automerge, if the conflict is the same as the earlier one recorded, it is noticed and a three\-way merge between the earlier conflicted automerge, the earlier manual resolution, and the current conflicted automerge is performed by the command\&. If this three\-way merge resolves cleanly, the result is written out to your working tree file, so you would not have to manually resolve it\&. Note that git\-rerere leaves the index file alone, so you still need to do the final sanity checks with git diff (or git diff \-c) and git update\-index when you are satisfied\&.
+
+
+As a convenience measure, git\-merge automatically invokes git\-rerere when it exits with a failed automerge, which records it if it is a new conflict, or reuses the earlier hand resolve when it is not\&. git\-commit also invokes git\-rerere when recording a merge result\&. What this means is that you do not have to do anything special yourself (Note: you still have to create $GIT_DIR/rr\-cache directory to enable this command)\&.
+
+
+In our example, when you did the test merge, the manual resolution is recorded, and it will be reused when you do the actual merge later with updated master and topic branch, as long as the earlier resolution is still applicable\&.
+
+
+The information git\-rerere records is also used when running git\-rebase\&. After blowing away the test merge and continuing development on the topic branch:
+
+.IP
+ o\-\-\-*\-\-\-o\-\-\-\-\-\-\-o\-\-\-o topic
+ /
+ o\-\-\-o\-\-\-o\-\-\-*\-\-\-o\-\-\-o\-\-\-o\-\-\-o master
+
+ $ git rebase master topic
+
+ o\-\-\-*\-\-\-o\-\-\-\-\-\-\-o\-\-\-o topic
+ /
+ o\-\-\-o\-\-\-o\-\-\-*\-\-\-o\-\-\-o\-\-\-o\-\-\-o master
+
+you could run git rebase master topic, to keep yourself up\-to\-date even before your topic is ready to be sent upstream\&. This would result in falling back to three\-way merge, and it would conflict the same way the test merge you resolved earlier\&. git\-rerere is run by git rebase to help you resolve this conflict\&.
+
+.SH "AUTHOR"
+
+
+Written by Junio C Hamano <junkio@cox\&.net>
+
+.SH "GIT"
+
+
+Part of the \fBgit\fR(7) suite
+
.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
.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"
.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"
\fBgit\-repack\fR(1)
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)
.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:
.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:
100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 2 hello\&.c
100644 cc44c73eb783565da5831b4d820c962954019b69 3 hello\&.c
-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:
projects / git.git / commitdiff