From 80cc278e7c819a4733131d43022cf58485390076 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Wed, 13 Dec 2006 21:32:36 +0000 Subject: [PATCH] Autogenerated man pages for v1.4.4.2-g1d77 --- man1/git-add.1 | 57 +++------ man1/git-branch.1 | 34 +++-- man1/git-commit.1 | 150 +++++++++++----------- man1/git-merge-index.1 | 22 ++-- man1/git-read-tree.1 | 71 ++++------- man1/git-repo-config.1 | 274 ++++++++--------------------------------- man1/git-rerere.1 | 46 +++---- 7 files changed, 224 insertions(+), 430 deletions(-) diff --git a/man1/git-add.1 b/man1/git-add.1 index 6b610c694..75c910210 100644 --- a/man1/git-add.1 +++ b/man1/git-add.1 @@ -2,26 +2,29 @@ .\" It was generated using the DocBook XSL Stylesheets (version 1.69.1). .\" Instead of manually editing it, you probably should edit the DocBook XML .\" source for it and then use the DocBook XSL Stylesheets to regenerate it. -.TH "GIT\-ADD" "1" "10/03/2006" "" "" +.TH "GIT\-ADD" "1" "12/13/2006" "" "" .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .SH "NAME" -git\-add \- Add files to the index file +git\-add \- Add file contents to the changeset to be committed next .SH "SYNOPSIS" \fIgit\-add\fR [\-n] [\-v] [\-\-] \&... -.sp .SH "DESCRIPTION" -A simple wrapper for git\-update\-index to add files to the index, for people used to do "cvs add". -.sp -It only adds non\-ignored files, to add ignored files use "git update\-index \-\-add". -.sp +All the changed file contents to be committed together in a single set of changes must be "added" with the \fIadd\fR command before using the \fIcommit\fR command. This is not only for adding new files. Even modified files must be added to the set of changes about to be committed. + +This command can be performed multiple times before a commit. The added content corresponds to the state of specified file(s) at the time the \fIadd\fR command is used. This means the \fIcommit\fR command will not consider subsequent changes to already added content if it is not added again before the commit. + +The \fIgit status\fR command can be used to obtain a summary of what is included for the next commit. + +This command only adds non\-ignored files, to add ignored files use "git update\-index \-\-add". + +Please see \fBgit\-commit\fR(1) for alternative ways to add content to a commit. .SH "OPTIONS" .TP \&... -Files to add to the index (see -\fBgit\-ls\-files\fR(1)). +Files to add content from. .TP \-n Don't actually add the file(s), just show if they exist. @@ -31,45 +34,21 @@ Be verbose. .TP \-\- This option can be used to separate command\-line options from the list of files, (useful when filenames might be mistaken for command\-line options). -.SH "DISCUSSION" -The list of given to the command is fed to git\-ls\-files command to list files that are not registered in the index and are not ignored/excluded by $GIT_DIR/info/exclude file or .gitignore file in each directory. This means two things: -.sp -.TP 3 -1. -You can put the name of a directory on the command line, and the command will add all files in it and its subdirectories; -.TP -2. -Giving the name of a file that is already in index does not run -git\-update\-index -on that path. .SH "EXAMPLES" .TP git\-add Documentation/\\*.txt -Adds all -*.txt -files that are not in the index under -Documentation -directory and its subdirectories. -.sp -Note that the asterisk -* -is quoted from the shell in this example; this lets the command to include the files from subdirectories of -Documentation/ -directory. +Adds content from all *.txt files under Documentation directory and its subdirectories. + +Note that the asterisk * is quoted from the shell in this example; this lets the command to include the files from subdirectories of Documentation/ directory. .TP git\-add git\-*.sh -Adds all git\-*.sh scripts that are not in the index. Because this example lets shell expand the asterisk (i.e. you are listing the files explicitly), it does not add -subdir/git\-foo.sh -to the index. +Considers adding content from all git\-*.sh scripts. Because this example lets shell expand the asterisk (i.e. you are listing the files explicitly), it does not consider subdir/git\-foo.sh. .SH "SEE ALSO" -\fBgit\-rm\fR(1) \fBgit\-ls\-files\fR(1) -.sp +\fBgit\-status\fR(1) \fBgit\-rm\fR(1) \fBgit\-mv\fR(1) \fBgit\-commit\fR(1) \fBgit\-update\-index\fR(1) .SH "AUTHOR" Written by Linus Torvalds -.sp .SH "DOCUMENTATION" Documentation by Junio C Hamano and the git\-list . -.sp .SH "GIT" Part of the \fBgit\fR(7) suite -.sp + diff --git a/man1/git-branch.1 b/man1/git-branch.1 index c3f9bee99..84bcda14b 100644 --- a/man1/git-branch.1 +++ b/man1/git-branch.1 @@ -2,7 +2,7 @@ .\" It was generated using the DocBook XSL Stylesheets (version 1.69.1). .\" Instead of manually editing it, you probably should edit the DocBook XML .\" source for it and then use the DocBook XSL Stylesheets to regenerate it. -.TH "GIT\-BRANCH" "1" "11/25/2006" "" "" +.TH "GIT\-BRANCH" "1" "12/13/2006" "" "" .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) @@ -12,17 +12,19 @@ git\-branch \- List, create, or delete branches. .SH "SYNOPSIS" .sp .nf -\fIgit\-branch\fR [\-r] [\-a] [\-v] [\-\-abbrev=] +\fIgit\-branch\fR [\-r | \-a] [\-v [\-\-abbrev=]] \fIgit\-branch\fR [\-l] [\-f] [] +\fIgit\-branch\fR (\-m | \-M) [] \fIgit\-branch\fR (\-d | \-D) \&... .fi .SH "DESCRIPTION" With no arguments given a list of existing branches will be shown, the current branch will be highlighted with an asterisk. Option \-r causes the remote\-tracking branches to be listed, and option \-a shows both. -.sp + In its second form, a new branch named will be created. It will start out with a head equal to the one given as . If no is given, the branch will be created with a head equal to that of the currently checked out branch. -.sp + +With a \fI\-m\fR or \fI\-M\fR option, will be renamed to . If had a corresponding reflog, it is renamed to match , and a reflog entry is created to remember the branch renaming. If exists, \-M must be used to force the rename to happen. + With a \-d or \-D option, will be deleted. You may specify more than one branch for deletion. If the branch currently has a ref log then the ref log will also be deleted. -.sp .SH "OPTIONS" .TP \-d @@ -37,6 +39,12 @@ Create the branch's ref log. This activates recording of all changes to made the \-f Force the creation of a new branch even if it means deleting a branch that already exists with the same name. .TP +\-m +Move/rename a branch and the corresponding reflog. +.TP +\-M +Move/rename a branch even if the new branchname already exists. +.TP \-r List the remote\-tracking branches. .TP @@ -44,17 +52,22 @@ List the remote\-tracking branches. List both remote\-tracking branches and local branches. .TP \-v -Show sha1 and subject message for each head. +Show sha1 and commit subjectline for each head. .TP \-\-abbrev= Alter minimum display length for sha1 in output listing, default value is 7. .TP -The name of the branch to create or delete. The new branch name must pass all checks defined by -\fBgit\-check\-ref\-format\fR(1). Some of these checks may restrict the characters allowed in a branch name. +The name of the branch to create or delete. The new branch name must pass all checks defined by \fBgit\-check\-ref\-format\fR(1). Some of these checks may restrict the characters allowed in a branch name. .TP The new branch will be created with a HEAD equal to this. It may be given as a branch name, a commit\-id, or a tag. If this option is omitted, the current branch is assumed. +.TP + +The name of an existing branch to rename. +.TP + +The new name for an existing branch. The same restrictions as for applies. .SH "EXAMPLES" .TP Start development off of a known tag @@ -81,13 +94,10 @@ $ git branch \-D todo \fB(1)\fR .br .SH "NOTES" If you are creating a branch that you want to immediately checkout, it's easier to use the git checkout command with its \-b option to create a branch and check it out with a single command. -.sp .SH "AUTHOR" Written by Linus Torvalds and Junio C Hamano -.sp .SH "DOCUMENTATION" Documentation by Junio C Hamano and the git\-list . -.sp .SH "GIT" Part of the \fBgit\fR(7) suite -.sp + diff --git a/man1/git-commit.1 b/man1/git-commit.1 index 940ea0596..6d4fe9019 100644 --- a/man1/git-commit.1 +++ b/man1/git-commit.1 @@ -2,7 +2,7 @@ .\" It was generated using the DocBook XSL Stylesheets (version 1.69.1). .\" Instead of manually editing it, you probably should edit the DocBook XML .\" source for it and then use the DocBook XSL Stylesheets to regenerate it. -.TH "GIT\-COMMIT" "1" "10/03/2006" "" "" +.TH "GIT\-COMMIT" "1" "12/13/2006" "" "" .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) @@ -17,32 +17,36 @@ git\-commit \- Record your changes [\-\-] [[\-i | \-o ]\&...] .fi .SH "DESCRIPTION" -Updates the index file for given paths, or all modified files if \fI\-a\fR is specified, and makes a commit object. The command specified by either the VISUAL or EDITOR environment variables are used to edit the commit log message. -.sp -Several environment variable are used during commits. They are documented in \fBgit\-commit\-tree\fR(1). -.sp -This command can run commit\-msg, pre\-commit, and post\-commit hooks. See [1]\&\fIhooks\fR for more information. -.sp +Use \fIgit commit\fR when you want to record your changes into the repository along with a log message describing what the commit is about. All changes to be committed must be explicitly identified using one of the following methods: +.TP 3 +1. +by using \fBgit\-add\fR(1) to incrementally "add" changes to the next commit before using the \fIcommit\fR command (Note: even modified files must be "added"); +.TP +2. +by using \fBgit\-rm\fR(1) to identify content removal for the next commit, again before using the \fIcommit\fR command; +.TP +3. +by directly listing files containing changes to be committed as arguments to the \fIcommit\fR command, in which cases only those files alone will be considered for the commit; +.TP +4. +by using the \-a switch with the \fIcommit\fR command to automatically "add" changes from all known files i.e. files that have already been committed before, and perform the actual commit. + +The \fBgit\-status\fR(1) command can be used to obtain a summary of what is included by any of the above for the next commit by giving the same set of parameters you would give to this command. + +If you make a commit and then found a mistake immediately after that, you can recover from it with \fBgit\-reset\fR(1). .SH "OPTIONS" .TP \-a|\-\-all -Update all paths in the index file. This flag notices files that have been modified and deleted, but new files you have not told git about are not affected. +Tell the command to automatically stage files that have been modified and deleted, but new files you have not told git about are not affected. .TP \-c or \-C -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. +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 -Take the commit message from the given file. Use -\fI\-\fR -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 -Override the author name used in the commit. Use -A U Thor -format. +Override the author name used in the commit. Use A U Thor format. .TP \-m Use the given as the commit message. @@ -50,25 +54,15 @@ Use the given as the commit message. \-s|\-\-signoff Add Signed\-off\-by line at the end of the commit message. .TP -\-v|\-\-verify -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 -The opposite of -\-\-verify. +\-\-no\-verify +By default, the command looks for suspicious lines the commit introduces, and aborts 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 option turns off the check. .TP \-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. +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 \-\-amend Used to amend the tip of the current branch. Prepare the tree object you would want to replace the latest commit as usual (this includes the usual \-i/\-o and explicit paths), and the commit log editor is seeded with the commit message from the tip of the current branch. The commit you create replaces the current tip \(em if it was a merge, it will have the parents of the current tip as parents \(em so the current top commit is discarded. -.sp + It is a rough equivalent for: .sp .nf @@ -79,68 +73,70 @@ It is a rough equivalent for: but can be used to amend a merge commit. .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 behavior. -.TP -\-o|\-\-only -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. +Before making a commit out of staged contents so far, stage the contents of paths given on the command line as well. This is usually not what you want unless you are concluding a conflicted merge. .TP \-\- Do not interpret any more arguments as options. .TP \&... -Files to be committed. The meaning of these is different between -\-\-include -and -\-\-only. Without either, it defaults -\-\-only -semantics. -If you make a commit and then found a mistake immediately after that, you can recover from it with \fBgit\-reset\fR(1). +When files are given on the command line, the command commits the contents of the named files, without recording the changes already staged. The contents of these files are also staged for the next commit on top of what have been staged before. +.SH "EXAMPLES" +When recording your own work, the contents of modified files in your working tree are temporarily stored to a staging area called the "index" with \fBgit\-add\fR(1). Removal of a file is staged with \fBgit\-rm\fR(1). After building the state to be committed incrementally with these commands, git commit (without any pathname parameter) is used to record what has been staged so far. This is the most basic form of the command. An example: .sp -.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. -.sp -git commit \-\-include paths\&... is equivalent to +.nf +$ edit hello.c +$ git rm goodbye.c +$ git add hello.c +$ git commit +.fi +Instead of staging files after each individual change, you can tell git commit to notice the changes to the files whose contents are tracked in your working tree and do corresponding git add and git rm for you. That is, this example does the same as the earlier example if there is no other change in your working tree: .sp +.nf +$ edit hello.c +$ rm goodbye.c +$ git commit \-a +.fi +The command git commit \-a first looks at your working tree, notices that you have modified hello.c and removed goodbye.c, and performs necessary git add and git rm for you. + +After staging changes to many files, you can alter the order the changes are recorded in, by giving pathnames to git commit. When pathnames are given, the command makes a commit that only records the changes made to the named paths: .sp .nf -git update\-index \-\-remove paths... -git commit +$ edit hello.c hello.h +$ git add hello.c hello.h +$ edit Makefile +$ git commit Makefile .fi -That is, update the specified paths to the index and then commit the whole tree. +This makes a commit that records the modification to Makefile. The changes staged for hello.c and hello.h are not included in the resulting commit. However, their changes are not lost \(em they are still staged and merely held back. After the above sequence, if you do: .sp -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. +.nf +$ git commit +.fi +this second commit would record the changes to hello.c and hello.h as expected. + +After a merge (initiated by either \fBgit\-merge\fR(1) or \fBgit\-pull\fR(1)) stops because of conflicts, cleanly merged paths are already staged to be committed for you, and paths that conflicted are left in unmerged state. You would have to first check which paths are conflicting with \fBgit\-status\fR(1) and after fixing them manually in your working tree, you would stage the result as usual with \fBgit\-add\fR(1): .sp -.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\&.... -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. +.nf +$ git status | grep unmerged +unmerged: hello.c +$ edit hello.c +$ git add hello.c +.fi +After resolving conflicts and staging the result, git ls\-files \-u would stop mentioning the conflicted path. When you are done, run git commit to finally record the merge: .sp +.nf +$ git commit +.fi +As with the case to record your own changes, you can use \-a option to save typing. One difference is that during a merge resolution, you cannot use git commit with pathnames to alter the order the changes are committed, because the merge should be recorded as a single commit. In fact, the command refuses to run when given pathnames (but see \-i option). +.SH "ENVIRONMENT VARIABLES" +The command specified by either the VISUAL or EDITOR environment variables is used to edit the commit log message. +.SH "HOOKS" +This command can run commit\-msg, pre\-commit, and post\-commit hooks. See [1]\&\fIhooks\fR for more information. +.SH "SEE ALSO" +\fBgit\-add\fR(1), \fBgit\-rm\fR(1), \fBgit\-mv\fR(1), \fBgit\-merge\fR(1), \fBgit\-commit\-tree\fR(1) .SH "AUTHOR" Written by Linus Torvalds and Junio C Hamano -.sp .SH "GIT" Part of the \fBgit\fR(7) suite -.sp .SH "REFERENCES" .TP 3 1.\ hooks diff --git a/man1/git-merge-index.1 b/man1/git-merge-index.1 index 89d6a998d..e656d4247 100644 --- a/man1/git-merge-index.1 +++ b/man1/git-merge-index.1 @@ -2,7 +2,7 @@ .\" It was generated using the DocBook XSL Stylesheets (version 1.69.1). .\" Instead of manually editing it, you probably should edit the DocBook XML .\" source for it and then use the DocBook XSL Stylesheets to regenerate it. -.TH "GIT\-MERGE\-INDEX" "1" "10/03/2006" "" "" +.TH "GIT\-MERGE\-INDEX" "1" "12/13/2006" "" "" .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) @@ -11,10 +11,8 @@ git\-merge\-index \- Runs a merge for files needing merging .SH "SYNOPSIS" \fIgit\-merge\-index\fR [\-o] [\-q] (\-a | \-\- | *) -.sp .SH "DESCRIPTION" This looks up the (s) in the index and, if there are any merge entries, passes the SHA1 hash for those files as arguments 1, 2, 3 (empty argument if no file), and as argument 4. File modes for the three files are passed as arguments 5, 6 and 7. -.sp .SH "OPTIONS" .TP \-\- @@ -28,17 +26,17 @@ Instead of stopping at the first failed merge, do all of them in one shot \- con .TP \-q Do not complain about failed merge program (the merge program failure usually indicates conflicts during merge). This is for porcelains which might want to emit custom messages. + If "git\-merge\-index" is called with multiple s (or \-a) then it processes them in turn only stopping if merge returns a non\-zero exit code. -.sp -Typically this is run with the a script calling the merge command from the RCS package. -.sp + +Typically this is run with the a script calling git's imitation of the merge command from the RCS package. + A sample script called "git\-merge\-one\-file" is included in the distribution. -.sp + ALERT ALERT ALERT! The git "merge object order" is different from the RCS "merge" program merge object order. In the above ordering, the original is first. But the argument order to the 3\-way merge program "merge" is to have the original in the middle. Don't ask me why. -.sp + Examples: .sp -.sp .nf torvalds@ppc970:~/merge\-test> git\-merge\-index cat MM This is MM from the original tree. # original @@ -48,7 +46,6 @@ This is modified MM in the branch B. # current contents .fi or .sp -.sp .nf torvalds@ppc970:~/merge\-test> git\-merge\-index cat AA MM cat: : No such file or directory @@ -58,13 +55,10 @@ This is added AA in the branch B. fatal: merge program failed .fi where the latter example shows how "git\-merge\-index" will stop trying to merge once anything has returned an error (i.e., "cat" returned an error for the AA file, because it didn't exist in the original, and thus "git\-merge\-index" didn't even try to merge the MM thing). -.sp .SH "AUTHOR" Written by Linus Torvalds One\-shot merge by Petr Baudis -.sp .SH "DOCUMENTATION" Documentation by David Greaves, Junio C Hamano and the git\-list . -.sp .SH "GIT" Part of the \fBgit\fR(7) suite -.sp + diff --git a/man1/git-read-tree.1 b/man1/git-read-tree.1 index d7b640619..aa94352a6 100644 --- a/man1/git-read-tree.1 +++ b/man1/git-read-tree.1 @@ -2,7 +2,7 @@ .\" It was generated using the DocBook XSL Stylesheets (version 1.69.1). .\" Instead of manually editing it, you probably should edit the DocBook XML .\" source for it and then use the DocBook XSL Stylesheets to regenerate it. -.TH "GIT\-READ\-TREE" "1" "10/03/2006" "" "" +.TH "GIT\-READ\-TREE" "1" "12/13/2006" "" "" .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) @@ -10,15 +10,13 @@ .SH "NAME" git\-read\-tree \- Reads tree information into the index .SH "SYNOPSIS" -\fIgit\-read\-tree\fR ( | [[\-m [\-\-aggressive] | \-\-reset | \-\-prefix=] [\-u | \-i]] [ []]) -.sp +\fIgit\-read\-tree\fR ( | [[\-m [\-\-aggressive] | \-\-reset | \-\-prefix=] [\-u | \-i]] [\-\-exclude\-per\-directory=] [ []]) .SH "DESCRIPTION" Reads the tree information given by into the index, but does not actually \fBupdate\fR any of the files it "caches". (see: \fBgit\-checkout\-index\fR(1)) -.sp + Optionally, it can merge a tree into the index, perform a fast\-forward (i.e. 2\-way) merge, or a 3\-way merge, with the \-m flag. When used with \-m, the \-u flag causes it to also update the files in the work tree with the result of the merge. -.sp + Trivial merges are done by git\-read\-tree itself. Only conflicting paths will be in unmerged state when git\-read\-tree returns. -.sp .SH "OPTIONS" .TP \-m @@ -34,9 +32,7 @@ After a successful merge, update the files in the work tree with the result of t Usually a merge requires the index file as well as the files in the working tree are up to date with the current head commit, in order not to lose local changes. This flag disables the check with the working tree and is meant to be used when creating a merge of trees that are not directly related to the current working tree status into a temporary index file. .TP \-\-aggressive -Usually a three\-way merge by -git\-read\-tree -resolves the merge for really trivial cases and leaves other cases unresolved in the index, so that Porcelains can implement different merge policies. This flag makes the command to resolve a few more cases internally: +Usually a three\-way merge by git\-read\-tree resolves the merge for really trivial cases and leaves other cases unresolved in the index, so that Porcelains can implement different merge policies. This flag makes the command to resolve a few more cases internally: .RS .TP 3 \(bu @@ -50,41 +46,34 @@ when both sides adds a path identically. The resolution is to add that path. .RE .TP \-\-prefix=/ -Keep the current index contents, and read the contents of named tree\-ish under directory at -. The original index file cannot have anything at the path - -itself, and have nothing in -/ -directory. Note that the -/ -value must end with a slash. +Keep the current index contents, and read the contents of named tree\-ish under directory at . The original index file cannot have anything at the path itself, and have nothing in / directory. Note that the / value must end with a slash. +.TP +\-\-exclude\-per\-directory= +When running the command with \-u and \-m options, the merge result may need to overwrite paths that are not tracked in the current branch. The command usually refuses to proceed with the merge to avoid losing such a path. However this safety valve sometimes gets in the way. For example, it often happens that the other branch added a file that used to be a generated file in your branch, and the safety valve triggers when you try to switch to that branch after you ran make but before running make clean to remove the generated file. This option tells the command to read per\-directory exclude file (usually \fI.gitignore\fR) and allows such an untracked but explicitly ignored file to be overwritten. .TP The id of the tree object(s) to be read/merged. .SH "MERGING" If \-m is specified, git\-read\-tree can perform 3 kinds of merge, a single tree merge if only 1 tree is given, a fast\-forward merge with 2 trees, or a 3\-way merge if 3 trees are provided. -.sp .SS "Single Tree Merge" If only 1 tree is specified, git\-read\-tree operates as if the user did not specify \-m, except that if the original index has an entry for a given pathname, and the contents of the path matches with the tree being read, the stat info from the index is used. (In other words, the index's stat()s take precedence over the merged tree's). -.sp + That means that if you do a git\-read\-tree \-m followed by a git\-checkout\-index \-f \-u \-a, the git\-checkout\-index only checks out the stuff that really changed. -.sp + This is used to avoid unnecessary false hits when git\-diff\-files is run after git\-read\-tree. -.sp .SS "Two Tree Merge" Typically, this is invoked as git\-read\-tree \-m $H $M, where $H is the head commit of the current repository, and $M is the head of a foreign tree, which is simply ahead of $H (i.e. we are in a fast forward situation). -.sp + When two trees are specified, the user is telling git\-read\-tree the following: -.sp .TP 3 1. The current index and work tree is derived from $H, but the user may have local changes in them since $H; .TP 2. The user wants to fast\-forward to $M. + In this case, the git\-read\-tree \-m $H $M command makes sure that no local change is lost as the result of this "merge". Here are the "carry forward" rules: .sp -.sp .nf I (index) H M Result \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- @@ -133,24 +122,21 @@ In this case, the git\-read\-tree \-m $H $M command makes sure that no local cha 21 no yes no exists exists fail .fi In all "keep index" cases, the index entry stays as in the original index file. If the entry were not up to date, git\-read\-tree keeps the copy in the work tree intact when operating under the \-u flag. -.sp + When this form of git\-read\-tree returns successfully, you can see what "local changes" you made are carried forward by running git\-diff\-index \-\-cached $M. Note that this does not necessarily match git\-diff\-index \-\-cached $H would have produced before such a two tree merge. This is because of cases 18 and 19 \-\-\- if you already had the changes in $M (e.g. maybe you picked it up via e\-mail in a patch form), git\-diff\-index \-\-cached $H would have told you about the change before this merge, but it would not show in git\-diff\-index \-\-cached $M output after two\-tree merge. -.sp .SS "3\-Way Merge" Each "index" entry has two bits worth of "stage" state. stage 0 is the normal one, and is the only one you'd see in any kind of normal use. -.sp + However, when you do git\-read\-tree with three trees, the "stage" starts out at 1. -.sp + This means that you can do .sp -.sp .nf $ git\-read\-tree \-m .fi and you will end up with an index with all of the entries in "stage1", all of the entries in "stage2" and all of the entries in "stage3". When performing a merge of another branch into the current branch, we use the common ancestor tree as , the current branch head as , and the other branch head as . -.sp + Furthermore, git\-read\-tree has special\-case logic that says: if you see a file that matches in all respects in the following states, it "collapses" back to "stage0": -.sp .TP 3 \(bu stage 2 and 3 are the same; take one or the other (it makes no difference \- the same work has been done on our branch in stage 2 and their branch in stage 3) @@ -160,12 +146,12 @@ stage 1 and stage 2 are the same and stage 3 is different; take stage 3 (our bra .TP \(bu stage 1 and stage 3 are the same and stage 2 is different take stage 2 (we did something while they did nothing) + The git\-write\-tree command refuses to write a nonsensical tree, and it will complain about unmerged entries if it sees a single entry that is not stage 0. -.sp + OK, this all sounds like a collection of totally nonsensical rules, but it's actually exactly what you want in order to do a fast merge. The different stages represent the "result tree" (stage 0, aka "merged"), the original tree (stage 1, aka "orig"), and the two trees you are trying to merge (stage 2 and 3 respectively). -.sp + The order of stages 1, 2 and 3 (hence the order of three command line arguments) are significant when you start a 3\-way merge with an index file that is already populated. Here is an outline of how the algorithm works: -.sp .TP 3 \(bu if a file exists in identical format in all three trees, it will automatically collapse to "merged" state by git\-read\-tree. @@ -187,26 +173,23 @@ if you find a "stage1", but no matching "stage2" or "stage3", you know it's been if you find a matching "stage2" and "stage3" tree, you remove one of them, and turn the other into a "stage0" entry. Remove any matching "stage1" entry if it exists too. .. all the normal trivial rules .. .RE You would normally use git\-merge\-index with supplied git\-merge\-one\-file to do this last step. The script updates the files in the working tree as it merges each path and at the end of a successful merge. -.sp + When you start a 3\-way merge with an index file that is already populated, it is assumed that it represents the state of the files in your work tree, and you can even have files with changes unrecorded in the index file. It is further assumed that this state is "derived" from the stage 2 tree. The 3\-way merge refuses to run if it finds an entry in the original index file that does not match stage 2. -.sp + This is done to prevent you from losing your work\-in\-progress changes, and mixing your random changes in an unrelated merge commit. To illustrate, suppose you start from what has been committed last to your repository: .sp -.sp .nf $ JC=`git\-rev\-parse \-\-verify "HEAD^0"` $ git\-checkout\-index \-f \-u \-a $JC .fi You do random edits, without running git\-update\-index. And then you notice that the tip of your "upstream" tree has advanced since you pulled from him: .sp -.sp .nf $ git\-fetch git://.... linus $ LT=`cat .git/FETCH_HEAD` .fi Your work tree is still based on your HEAD ($JC), but you have some edits since. Three\-way merge makes sure that you have not added or modified index entries since $JC, and if you haven't, then does the right thing. So with the following sequence: .sp -.sp .nf $ git\-read\-tree \-m \-u `git\-merge\-base $JC $LT` $JC $LT $ git\-merge\-index git\-merge\-one\-file \-a @@ -214,20 +197,16 @@ $ echo "Merge with Linus" | \\ git\-commit\-tree `git\-write\-tree` \-p $JC \-p $LT .fi what you would commit is a pure merge between $JC and $LT without your work\-in\-progress changes, and your work tree would be updated to the result of the merge. -.sp + However, if you have local changes in the working tree that would be overwritten by this merge,git\-read\-tree will refuse to run to prevent your changes from being lost. -.sp + In other words, there is no need to worry about what exists only in the working tree. When you have local changes in a part of the project that is not involved in the merge, your changes do not interfere with the merge, and are kept intact. When they \fBdo\fR interfere, the merge does not even start (git\-read\-tree complains loudly and fails without modifying anything). In such a case, you can simply continue doing what you were in the middle of doing, and when your working tree is ready (i.e. you have finished your work\-in\-progress), attempt the merge again. -.sp .SH "SEE ALSO" \fBgit\-write\-tree\fR(1); \fBgit\-ls\-files\fR(1) -.sp .SH "AUTHOR" Written by Linus Torvalds -.sp .SH "DOCUMENTATION" Documentation by David Greaves, Junio C Hamano and the git\-list . -.sp .SH "GIT" Part of the \fBgit\fR(7) suite -.sp + diff --git a/man1/git-repo-config.1 b/man1/git-repo-config.1 index 203bc44cb..444e338f2 100644 --- a/man1/git-repo-config.1 +++ b/man1/git-repo-config.1 @@ -22,13 +22,12 @@ git\-repo\-config \- Get and set repository or global options. .fi .SH "DESCRIPTION" You can query/set/replace/unset options with this command. The name is actually the section and the key separated by a dot, and the value will be escaped. -.sp + If you want to set/unset an option which can occur on multiple lines, a POSIX regexp value_regex needs to be given. Only the existing values that match the regexp are updated or unset. If you want to handle the lines that do \fBnot\fR match the regex, just prepend a single exclamation mark in front (see EXAMPLES). -.sp + The type specifier can be either \fI\-\-int\fR or \fI\-\-bool\fR, which will make \fIgit\-repo\-config\fR ensure that the variable(s) are of the given type and convert the value to the canonical form (simple decimal number for int, a "true" or "false" string for bool). If no type specifier is passed, no checks or transformations are performed on the value. -.sp + This command will fail if: -.sp .TP 3 1. The .git/config file is invalid, @@ -91,7 +90,6 @@ Currently the same as $GIT_CONFIG; when Git will support global configuration fi .SH "EXAMPLE" Given a .git/config like this: .sp -.sp .nf # # This is the config file, and @@ -124,73 +122,62 @@ Given a .git/config like this: .fi you can set the filemode to true with .sp -.sp .nf % git repo\-config core.filemode true .fi The hypothetical proxy command entries actually have a postfix to discern what URL they apply to. Here is how to change the entry for kernel.org to "ssh". .sp -.sp .nf % git repo\-config core.gitproxy '"ssh" for kernel.org' 'for kernel.org$' .fi This makes sure that only the key/value pair for kernel.org is replaced. -.sp + To delete the entry for renames, do .sp -.sp .nf % git repo\-config \-\-unset diff.renames .fi If you want to delete an entry for a multivar (like core.gitproxy above), you have to provide a regex matching the value of exactly one line. -.sp + To query the value for a given key, do .sp -.sp .nf % git repo\-config \-\-get core.filemode .fi or .sp -.sp .nf % git repo\-config core.filemode .fi or, to query a multivar: .sp -.sp .nf % git repo\-config \-\-get core.gitproxy "for kernel.org$" .fi If you want to know all the values for a multivar, do: .sp -.sp .nf % git repo\-config \-\-get\-all core.gitproxy .fi If you like to live dangerous, you can replace \fBall\fR core.gitproxy by a new one with .sp -.sp .nf % git repo\-config \-\-replace\-all core.gitproxy ssh .fi However, if you really only want to replace the line for the default proxy, i.e. the one without a "for \&..." postfix, do something like this: .sp -.sp .nf % git repo\-config core.gitproxy ssh '! for ' .fi To actually match only values with an exclamation mark, you have to .sp -.sp .nf % git repo\-config section.key value '[!]' .fi .SH "CONFIGURATION FILE" The git configuration file contains a number of variables that affect the git command's behavior. They can be used by both the git plumbing and the porcelains. The variables are divided into sections, where in the fully qualified variable name the variable itself is the last dot\-separated segment and the section name is everything before the last dot. The variable names are case\-insensitive and only alphanumeric characters are allowed. Some variables may appear multiple times. -.sp + The syntax is fairly flexible and permissive; whitespaces are mostly ignored. The \fI#\fR and \fI;\fR characters begin comments to the end of line, blank lines are ignored, lines containing strings enclosed in square brackets start sections and all the other lines are recognized as setting variables, in the form \fIname = value\fR. If there is no equal sign on the line, the entire line is taken as \fIname\fR and the variable is recognized as boolean "true". String values may be entirely or partially enclosed in double quotes; some variables may require special value format. -.sp .SS "Example" .sp .nf @@ -208,23 +195,17 @@ The syntax is fairly flexible and permissive; whitespaces are mostly ignored. Th .fi .SS "Variables" Note that this list is non\-comprehensive and not necessarily complete. For command\-specific variables, you will find a more detailed description in the appropriate manual page. You will find a description of non\-core porcelain configuration variables in the respective porcelain documentation. -.sp .TP core.fileMode -If false, the executable bit differences between the index and the working copy are ignored; useful on broken filesystems like FAT. See -\fBgit\-update\-index\fR(1). True by default. +If false, the executable bit differences between the index and the working copy are ignored; useful on broken filesystems like FAT. See \fBgit\-update\-index\fR(1). True by default. .TP core.gitProxy -A "proxy command" to execute (as -\fIcommand host port\fR) instead of establishing direct connection to the remote server when using the git protocol for fetching. If the variable value is in the "COMMAND for DOMAIN" format, the command is applied only on hostnames ending with the specified domain string. This variable may be set multiple times and is matched in the given order; the first match wins. -.sp -Can be overridden by the -\fIGIT_PROXY_COMMAND\fR -environment variable (which always applies universally, without the special "for" handling). +A "proxy command" to execute (as \fIcommand host port\fR) instead of establishing direct connection to the remote server when using the git protocol for fetching. If the variable value is in the "COMMAND for DOMAIN" format, the command is applied only on hostnames ending with the specified domain string. This variable may be set multiple times and is matched in the given order; the first match wins. + +Can be overridden by the \fIGIT_PROXY_COMMAND\fR environment variable (which always applies universally, without the special "for" handling). .TP core.ignoreStat -The working copy files are assumed to stay unchanged until you mark them otherwise manually \- Git will not detect the file changes by lstat() calls. This is useful on systems where those are very slow, such as Microsoft Windows. See -\fBgit\-update\-index\fR(1). False by default. +The working copy files are assumed to stay unchanged until you mark them otherwise manually \- Git will not detect the file changes by lstat() calls. This is useful on systems where those are very slow, such as Microsoft Windows. See \fBgit\-update\-index\fR(1). False by default. .TP core.preferSymlinkRefs Instead of the default "symref" format for HEAD and other symbolic reference files, use symbolic links. This is sometimes needed to work with old scripts that expect HEAD to be a symbolic link. @@ -242,19 +223,7 @@ core.repositoryFormatVersion Internal variable identifying the repository format and layout version. .TP core.sharedRepository -When -\fIgroup\fR -(or -\fItrue\fR), the repository is made shareable between several users in a group (making sure all the files and objects are group\-writable). When -\fIall\fR -(or -\fIworld\fR -or -\fIeverybody\fR), the repository will be readable by all users, additionally to being group\-shareable. When -\fIumask\fR -(or -\fIfalse\fR), git will use permissions reported by umask(2). See -\fBgit\-init\-db\fR(1). False by default. +When \fIgroup\fR (or \fItrue\fR), the repository is made shareable between several users in a group (making sure all the files and objects are group\-writable). When \fIall\fR (or \fIworld\fR or \fIeverybody\fR), the repository will be readable by all users, additionally to being group\-shareable. When \fIumask\fR (or \fIfalse\fR), git will use permissions reported by umask(2). See \fBgit\-init\-db\fR(1). False by default. .TP core.warnAmbiguousRefs If true, git will warn you if the ref name you passed it is ambiguous and might match multiple refs in the .git/refs/ tree. True by default. @@ -266,157 +235,82 @@ core.legacyheaders A boolean which enables the legacy object header format in case you want to interoperate with old clients accessing the object database directly (where the "http://" and "rsync://" protocols count as direct access). .TP alias.* -Command aliases for the -\fBgit\fR(1) -command wrapper \- e.g. after defining "alias.last = cat\-file commit HEAD", the invocation "git last" is equivalent to "git cat\-file commit HEAD". To avoid confusion and troubles with script usage, aliases that hide existing git commands are ignored. Arguments are split by spaces, the usual shell quoting and escaping is supported. quote pair and a backslash can be used to quote them. +Command aliases for the \fBgit\fR(1) command wrapper \- e.g. after defining "alias.last = cat\-file commit HEAD", the invocation "git last" is equivalent to "git cat\-file commit HEAD". To avoid confusion and troubles with script usage, aliases that hide existing git commands are ignored. Arguments are split by spaces, the usual shell quoting and escaping is supported. quote pair and a backslash can be used to quote them. .TP apply.whitespace -Tells -git\-apply -how to handle whitespaces, in the same way as the -\fI\-\-whitespace\fR -option. See -\fBgit\-apply\fR(1). +Tells git\-apply how to handle whitespaces, in the same way as the \fI\-\-whitespace\fR option. See \fBgit\-apply\fR(1). .TP branch..remote -When in branch , it tells -git fetch -which remote to fetch. If this option is not given, -git fetch -defaults to remote "origin". +When in branch , it tells git fetch which remote to fetch. If this option is not given, git fetch defaults to remote "origin". .TP branch..merge -When in branch , it tells -git fetch -the default refspec to be marked for merging in FETCH_HEAD. The value has exactly to match a remote part of one of the refspecs which are fetched from the remote given by "branch..remote". The merge information is used by -git pull -(which at first calls -git fetch) to lookup the default branch for merging. Without this option, -git pull -defaults to merge the first refspec fetched. Specify multiple values to get an octopus merge. +When in branch , it tells git fetch the default refspec to be marked for merging in FETCH_HEAD. The value has exactly to match a remote part of one of the refspecs which are fetched from the remote given by "branch..remote". The merge information is used by git pull (which at first calls git fetch) to lookup the default branch for merging. Without this option, git pull defaults to merge the first refspec fetched. Specify multiple values to get an octopus merge. +.TP +color.diff +When true (or always), always use colors in patch. When false (or never), never. When set to auto, use colors only when the output is to the terminal. +.TP +color.diff. +Use customized color for diff colorization. specifies which part of the patch to use the specified color, and is one of plain (context text), meta (metainformation), frag (hunk header), old (removed lines), or new (added lines). The value for these configuration variables can be one of: normal, bold, dim, ul, blink, reverse, reset, black, red, green, yellow, blue, magenta, cyan, or white. .TP color.pager A boolean to enable/disable colored output when the pager is in use (default is true). .TP -color.diff -When true (or -always), always use colors in patch. When false (or -never), never. When set to -auto, use colors only when the output is to the terminal. +color.status +A boolean to enable/disable color in the output of \fBgit\-status\fR(1). May be set to true (or always), false (or never) or auto, in which case colors are used only when the output is to a terminal. Defaults to false. .TP -color.diff. -Use customized color for diff colorization. - -specifies which part of the patch to use the specified color, and is one of -plain -(context text), -meta -(metainformation), -frag -(hunk header), -old -(removed lines), or -new -(added lines). The value for these configuration variables can be one of: -normal, -bold, -dim, -ul, -blink, -reverse, -reset, -black, -red, -green, -yellow, -blue, -magenta, -cyan, or -white. +color.status. +Use customized color for status colorization. is one of header (the header text of the status message), updated (files which are updated but not committed), changed (files which are changed but not updated in the index), or untracked (files which are not tracked by git). The values of these variables may be specified as in color.diff.. .TP diff.renameLimit -The number of files to consider when performing the copy/rename detection; equivalent to the git diff option -\fI\-l\fR. +The number of files to consider when performing the copy/rename detection; equivalent to the git diff option \fI\-l\fR. .TP diff.renames Tells git to detect renames. If set to any boolean value, it will enable basic rename detection. If set to "copies" or "copy", it will detect copies, as well. .TP format.headers -Additional email headers to include in a patch to be submitted by mail. See -\fBgit\-format\-patch\fR(1). +Additional email headers to include in a patch to be submitted by mail. See \fBgit\-format\-patch\fR(1). .TP gitcvs.enabled -Whether the cvs pserver interface is enabled for this repository. See -\fBgit\-cvsserver\fR(1). +Whether the cvs pserver interface is enabled for this repository. See \fBgit\-cvsserver\fR(1). .TP gitcvs.logfile -Path to a log file where the cvs pserver interface well\&... logs various stuff. See -\fBgit\-cvsserver\fR(1). +Path to a log file where the cvs pserver interface well\&... logs various stuff. See \fBgit\-cvsserver\fR(1). .TP http.sslVerify -Whether to verify the SSL certificate when fetching or pushing over HTTPS. Can be overridden by the -\fIGIT_SSL_NO_VERIFY\fR -environment variable. +Whether to verify the SSL certificate when fetching or pushing over HTTPS. Can be overridden by the \fIGIT_SSL_NO_VERIFY\fR environment variable. .TP http.sslCert -File containing the SSL certificate when fetching or pushing over HTTPS. Can be overridden by the -\fIGIT_SSL_CERT\fR -environment variable. +File containing the SSL certificate when fetching or pushing over HTTPS. Can be overridden by the \fIGIT_SSL_CERT\fR environment variable. .TP http.sslKey -File containing the SSL private key when fetching or pushing over HTTPS. Can be overridden by the -\fIGIT_SSL_KEY\fR -environment variable. +File containing the SSL private key when fetching or pushing over HTTPS. Can be overridden by the \fIGIT_SSL_KEY\fR environment variable. .TP http.sslCAInfo -File containing the certificates to verify the peer with when fetching or pushing over HTTPS. Can be overridden by the -\fIGIT_SSL_CAINFO\fR -environment variable. +File containing the certificates to verify the peer with when fetching or pushing over HTTPS. Can be overridden by the \fIGIT_SSL_CAINFO\fR environment variable. .TP http.sslCAPath -Path containing files with the CA certificates to verify the peer with when fetching or pushing over HTTPS. Can be overridden by the -\fIGIT_SSL_CAPATH\fR -environment variable. +Path containing files with the CA certificates to verify the peer with when fetching or pushing over HTTPS. Can be overridden by the \fIGIT_SSL_CAPATH\fR environment variable. .TP http.maxRequests -How many HTTP requests to launch in parallel. Can be overridden by the -\fIGIT_HTTP_MAX_REQUESTS\fR -environment variable. Default is 5. +How many HTTP requests to launch in parallel. Can be overridden by the \fIGIT_HTTP_MAX_REQUESTS\fR environment variable. Default is 5. .TP http.lowSpeedLimit, http.lowSpeedTime -If the HTTP transfer speed is less than -\fIhttp.lowSpeedLimit\fR -for longer than -\fIhttp.lowSpeedTime\fR -seconds, the transfer is aborted. Can be overridden by the -\fIGIT_HTTP_LOW_SPEED_LIMIT\fR -and -\fIGIT_HTTP_LOW_SPEED_TIME\fR -environment variables. +If the HTTP transfer speed is less than \fIhttp.lowSpeedLimit\fR for longer than \fIhttp.lowSpeedTime\fR seconds, the transfer is aborted. Can be overridden by the \fIGIT_HTTP_LOW_SPEED_LIMIT\fR and \fIGIT_HTTP_LOW_SPEED_TIME\fR environment variables. .TP http.noEPSV -A boolean which disables using of EPSV ftp command by curl. This can helpful with some "poor" ftp servers which doesn't support EPSV mode. Can be overridden by the -\fIGIT_CURL_FTP_NO_EPSV\fR -environment variable. Default is false (curl will use EPSV). +A boolean which disables using of EPSV ftp command by curl. This can helpful with some "poor" ftp servers which doesn't support EPSV mode. Can be overridden by the \fIGIT_CURL_FTP_NO_EPSV\fR environment variable. Default is false (curl will use EPSV). .TP i18n.commitEncoding -Character encoding the commit messages are stored in; git itself does not care per se, but this information is necessary e.g. when importing commits from emails or in the gitk graphical history browser (and possibly at other places in the future or in other porcelains). See e.g. -\fBgit\-mailinfo\fR(1). Defaults to -\fIutf\-8\fR. +Character encoding the commit messages are stored in; git itself does not care per se, but this information is necessary e.g. when importing commits from emails or in the gitk graphical history browser (and possibly at other places in the future or in other porcelains). See e.g. \fBgit\-mailinfo\fR(1). Defaults to \fIutf\-8\fR. .TP log.showroot -If true, the initial commit will be shown as a big creation event. This is equivalent to a diff against an empty tree. Tools like -\fBgit\-log\fR(1) -or -\fBgit\-whatchanged\fR(1), which normally hide the root commit will now show it. True by default. +If true, the initial commit will be shown as a big creation event. This is equivalent to a diff against an empty tree. Tools like \fBgit\-log\fR(1) or \fBgit\-whatchanged\fR(1), which normally hide the root commit will now show it. True by default. .TP merge.summary Whether to include summaries of merged commits in newly created merge commit messages. False by default. .TP pack.window -The size of the window used by -\fBgit\-pack\-objects\fR(1) -when no window size is given on the command line. Defaults to 10. +The size of the window used by \fBgit\-pack\-objects\fR(1) when no window size is given on the command line. Defaults to 10. .TP pull.octopus The default merge strategy to use when pulling multiple branches at once. @@ -425,97 +319,37 @@ pull.twohead The default merge strategy to use when pulling a single branch. .TP remote..url -The URL of a remote repository. See -\fBgit\-fetch\fR(1) -or -\fBgit\-push\fR(1). +The URL of a remote repository. See \fBgit\-fetch\fR(1) or \fBgit\-push\fR(1). .TP remote..fetch -The default set of "refspec" for -\fBgit\-fetch\fR(1). See -\fBgit\-fetch\fR(1). +The default set of "refspec" for \fBgit\-fetch\fR(1). See \fBgit\-fetch\fR(1). .TP remote..push -The default set of "refspec" for -\fBgit\-push\fR(1). See -\fBgit\-push\fR(1). +The default set of "refspec" for \fBgit\-push\fR(1). See \fBgit\-push\fR(1). .TP repack.usedeltabaseoffset -Allow -\fBgit\-repack\fR(1) -to create packs that uses delta\-base offset. Defaults to false. +Allow \fBgit\-repack\fR(1) to create packs that uses delta\-base offset. Defaults to false. .TP show.difftree -The default -\fBgit\-diff\-tree\fR(1) -arguments to be used for -\fBgit\-show\fR(1). +The default \fBgit\-diff\-tree\fR(1) arguments to be used for \fBgit\-show\fR(1). .TP showbranch.default -The default set of branches for -\fBgit\-show\-branch\fR(1). See -\fBgit\-show\-branch\fR(1). -.TP -color.status -A boolean to enable/disable color in the output of -\fBgit\-status\fR(1). May be set to -true -(or -always), -false -(or -never) or -auto, in which case colors are used only when the output is to a terminal. Defaults to false. -.TP -color.status. -Use customized color for status colorization. - -is one of -header -(the header text of the status message), -updated -(files which are updated but not committed), -changed -(files which are changed but not updated in the index), or -untracked -(files which are not tracked by git). The values of these variables may be specified as in color.diff.. +The default set of branches for \fBgit\-show\-branch\fR(1). See \fBgit\-show\-branch\fR(1). .TP tar.umask -By default, -\fBgit\-tar\-tree\fR(1) -sets file and directories modes to 0666 or 0777. While this is both useful and acceptable for projects such as the Linux Kernel, it might be excessive for other projects. With this variable, it becomes possible to tell -\fBgit\-tar\-tree\fR(1) -to apply a specific umask to the modes above. The special value "user" indicates that the user's current umask will be used. This should be enough for most projects, as it will lead to the same permissions as -\fBgit\-checkout\fR(1) -would use. The default value remains 0, which means world read\-write. +By default, \fBgit\-tar\-tree\fR(1) sets file and directories modes to 0666 or 0777. While this is both useful and acceptable for projects such as the Linux Kernel, it might be excessive for other projects. With this variable, it becomes possible to tell \fBgit\-tar\-tree\fR(1) to apply a specific umask to the modes above. The special value "user" indicates that the user's current umask will be used. This should be enough for most projects, as it will lead to the same permissions as \fBgit\-checkout\fR(1) would use. The default value remains 0, which means world read\-write. .TP user.email -Your email address to be recorded in any newly created commits. Can be overridden by the -\fIGIT_AUTHOR_EMAIL\fR -and -\fIGIT_COMMITTER_EMAIL\fR -environment variables. See -\fBgit\-commit\-tree\fR(1). +Your email address to be recorded in any newly created commits. Can be overridden by the \fIGIT_AUTHOR_EMAIL\fR and \fIGIT_COMMITTER_EMAIL\fR environment variables. See \fBgit\-commit\-tree\fR(1). .TP user.name -Your full name to be recorded in any newly created commits. Can be overridden by the -\fIGIT_AUTHOR_NAME\fR -and -\fIGIT_COMMITTER_NAME\fR -environment variables. See -\fBgit\-commit\-tree\fR(1). +Your full name to be recorded in any newly created commits. Can be overridden by the \fIGIT_AUTHOR_NAME\fR and \fIGIT_COMMITTER_NAME\fR environment variables. See \fBgit\-commit\-tree\fR(1). .TP whatchanged.difftree -The default -\fBgit\-diff\-tree\fR(1) -arguments to be used for -\fBgit\-whatchanged\fR(1). +The default \fBgit\-diff\-tree\fR(1) arguments to be used for \fBgit\-whatchanged\fR(1). .TP imap -The configuration variables in the -\fIimap\fR -section are described in -\fBgit\-imap\-send\fR(1). +The configuration variables in the \fIimap\fR section are described in \fBgit\-imap\-send\fR(1). .TP receive.unpackLimit If the number of objects received in a push is below this limit then the objects will be unpacked into loose object files. However if the number of received objects equals or exceeds this limit then the received pack will be stored as a pack, after adding any missing delta bases. Storing the pack from a push can make the push operation complete faster, especially on slow filesystems. @@ -524,10 +358,8 @@ receive.denyNonFastForwards If set to true, git\-receive\-pack will deny a ref update which is not a fast forward. Use this to prevent such an update via a push, even if that push is forced. This configuration variable is set when initializing a shared repository. .SH "AUTHOR" Written by Johannes Schindelin -.sp .SH "DOCUMENTATION" Documentation by Johannes Schindelin, Petr Baudis and the git\-list . -.sp .SH "GIT" Part of the \fBgit\fR(7) suite -.sp + diff --git a/man1/git-rerere.1 b/man1/git-rerere.1 index e36c668c8..1270e8606 100644 --- a/man1/git-rerere.1 +++ b/man1/git-rerere.1 @@ -2,7 +2,7 @@ .\" It was generated using the DocBook XSL Stylesheets (version 1.69.1). .\" Instead of manually editing it, you probably should edit the DocBook XML .\" source for it and then use the DocBook XSL Stylesheets to regenerate it. -.TH "GIT\-RERERE" "1" "10/03/2006" "" "" +.TH "GIT\-RERERE" "1" "12/13/2006" "" "" .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) @@ -10,25 +10,35 @@ .SH "NAME" git\-rerere \- Reuse recorded resolve .SH "SYNOPSIS" -\fIgit\-rerere\fR -.sp +\fIgit\-rerere\fR [clear|diff|status] .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). -.sp + 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. .sp -.sp .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br \fBNote\fR You need to create $GIT_DIR/rr\-cache directory to enable this command. -.sp +.SH "COMMANDS" +Normally, git\-rerere is run without arguments or user\-intervention. However, it has several commands that allow it to interact with its working state. +.TP +\fIclear\fR +This resets the metadata used by rerere if a merge resolution is to be is aborted. Calling \fBgit\-am\fR(1) \-\-skip or \fBgit\-rebase\fR(1) [\-\-skip|\-\-abort] will automatcally invoke this command. +.TP +\fIdiff\fR +This displays diffs for the current state of the resolution. It is useful for tracking what has changed while the user is resolving conflicts. Additional arguments are passed directly to the system diff(1) command installed in PATH. +.TP +\fIstatus\fR +Like diff, but this only prints the filenames that will be tracked for resolutions. +.TP +\fIgc\fR +This command is used to prune records of conflicted merge that occurred long time ago. .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: .sp -.sp .nf o\-\-\-*\-\-\-o topic / @@ -36,7 +46,6 @@ When your topic branch modifies overlapping area that your master branch (or ups .fi 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: .sp -.sp .nf $ git checkout topic $ git pull . master @@ -46,10 +55,9 @@ For such a test, you need to merge master and topic somehow. One way to do it is o\-\-\-o\-\-\-o\-\-\-*\-\-\-o\-\-\-o master .fi 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. -.sp + 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: .sp -.sp .nf $ git checkout topic $ git pull . master @@ -62,10 +70,9 @@ After this test merge, there are two ways to continue your work on the topic. Th o\-\-\-o\-\-\-o\-\-\-*\-\-\-o\-\-\-o\-\-\-o\-\-\-o\-\-\-+ master .fi 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". -.sp + 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: .sp -.sp .nf $ git checkout topic $ git pull . master @@ -79,18 +86,17 @@ As an alternative, to keep the topic branch clean of test merges, you could blow o\-\-\-o\-\-\-o\-\-\-*\-\-\-o\-\-\-o\-\-\-o\-\-\-o\-\-\-+ master .fi 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. -.sp + 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. -.sp + 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. -.sp + 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). -.sp + 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. -.sp + 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: .sp -.sp .nf o\-\-\-*\-\-\-o\-\-\-\-\-\-\-o\-\-\-o topic / @@ -103,10 +109,8 @@ The information git\-rerere records is also used when running git\-rebase. After o\-\-\-o\-\-\-o\-\-\-*\-\-\-o\-\-\-o\-\-\-o\-\-\-o master .fi 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. -.sp .SH "AUTHOR" Written by Junio C Hamano -.sp .SH "GIT" Part of the \fBgit\fR(7) suite -.sp + -- 2.26.2