diff options
Diffstat (limited to 'Documentation/git-merge.txt')
| -rw-r--r-- | Documentation/git-merge.txt | 407 |
1 files changed, 279 insertions, 128 deletions
diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt index 55bc367479..3ceefb8a1f 100644 --- a/Documentation/git-merge.txt +++ b/Documentation/git-merge.txt @@ -9,18 +9,56 @@ git-merge - Join two or more development histories together SYNOPSIS -------- [verse] -'git-merge' [-n] [--stat] [--no-commit] [--squash] [-s <strategy>]... - [-m <msg>] <remote> <remote>... -'git-merge' <msg> HEAD <remote>... +'git merge' [-n] [--stat] [--no-commit] [--squash] [--[no-]edit] + [-s <strategy>] [-X <strategy-option>] + [--[no-]rerere-autoupdate] [-m <msg>] [<commit>...] +'git merge' <msg> HEAD <commit>... +'git merge' --abort DESCRIPTION ----------- -This is the top-level interface to the merge machinery -which drives multiple merge strategy scripts. - -The second syntax (<msg> `HEAD` <remote>) is supported for +Incorporates changes from the named commits (since the time their +histories diverged from the current branch) into the current +branch. This command is used by 'git pull' to incorporate changes +from another repository and can be used by hand to merge changes +from one branch into another. + +Assume the following history exists and the current branch is +"`master`": + +------------ + A---B---C topic + / + D---E---F---G master +------------ + +Then "`git merge topic`" will replay the changes made on the +`topic` branch since it diverged from `master` (i.e., `E`) until +its current commit (`C`) on top of `master`, and record the result +in a new commit along with the names of the two parent commits and +a log message from the user describing the changes. + +------------ + A---B---C topic + / \ + D---E---F---G---H master +------------ + +The second syntax (<msg> `HEAD` <commit>...) is supported for historical reasons. Do not use it from the command line or in -new scripts. It is the same as `git merge -m <msg> <remote>`. +new scripts. It is the same as `git merge -m <msg> <commit>...`. + +The third syntax ("`git merge --abort`") can only be run after the +merge has resulted in conflicts. 'git merge --abort' will abort the +merge process and try to reconstruct the pre-merge state. However, +if there were uncommitted changes when the merge started (and +especially if those changes were further modified after the merge +was started), 'git merge --abort' will in some cases be unable to +reconstruct the original (pre-merge) changes. Therefore: + +*Warning*: Running 'git merge' with uncommitted changes is +discouraged: while possible, it leaves you in a state that is hard to +back out of in the case of a conflict. OPTIONS @@ -28,143 +66,256 @@ OPTIONS include::merge-options.txt[] -m <msg>:: - The commit message to be used for the merge commit (in case - it is created). The `git-fmt-merge-msg` script can be used - to give a good default for automated `git-merge` invocations. + Set the commit message to be used for the merge commit (in + case one is created). ++ +If `--log` is specified, a shortlog of the commits being merged +will be appended to the specified message. ++ +The 'git fmt-merge-msg' command can be +used to give a good default for automated 'git merge' +invocations. + +--rerere-autoupdate:: +--no-rerere-autoupdate:: + Allow the rerere mechanism to update the index with the + result of auto-conflict resolution if possible. + +--abort:: + Abort the current conflict resolution process, and + try to reconstruct the pre-merge state. ++ +If there were uncommitted worktree changes present when the merge +started, 'git merge --abort' will in some cases be unable to +reconstruct these changes. It is therefore recommended to always +commit or stash your changes before running 'git merge'. ++ +'git merge --abort' is equivalent to 'git reset --merge' when +`MERGE_HEAD` is present. + +<commit>...:: + Commits, usually other branch heads, to merge into our branch. + Specifying more than one commit will create a merge with + more than two parents (affectionately called an Octopus merge). ++ +If no commit is given from the command line, and if `merge.defaultToUpstream` +configuration variable is set, merge the remote tracking branches +that the current branch is configured to use as its upstream. +See also the configuration section of this manual page. + + +PRE-MERGE CHECKS +---------------- + +Before applying outside changes, you should get your own work in +good shape and committed locally, so it will not be clobbered if +there are conflicts. See also linkgit:git-stash[1]. +'git pull' and 'git merge' will stop without doing anything when +local uncommitted changes overlap with files that 'git pull'/'git +merge' may need to update. + +To avoid recording unrelated changes in the merge commit, +'git pull' and 'git merge' will also abort if there are any changes +registered in the index relative to the `HEAD` commit. (One +exception is when the changed index entries are in the state that +would result from the merge already.) + +If all named commits are already ancestors of `HEAD`, 'git merge' +will exit early with the message "Already up-to-date." + +FAST-FORWARD MERGE +------------------ + +Often the current branch head is an ancestor of the named commit. +This is the most common case especially when invoked from 'git +pull': you are tracking an upstream repository, you have committed +no local changes, and now you want to update to a newer upstream +revision. In this case, a new commit is not needed to store the +combined history; instead, the `HEAD` (along with the index) is +updated to point at the named commit, without creating an extra +merge commit. + +This behavior can be suppressed with the `--no-ff` option. + +TRUE MERGE +---------- + +Except in a fast-forward merge (see above), the branches to be +merged must be tied together by a merge commit that has both of them +as its parents. + +A merged version reconciling the changes from all branches to be +merged is committed, and your `HEAD`, index, and working tree are +updated to it. It is possible to have modifications in the working +tree as long as they do not overlap; the update will preserve them. + +When it is not obvious how to reconcile the changes, the following +happens: + +1. The `HEAD` pointer stays the same. +2. The `MERGE_HEAD` ref is set to point to the other branch head. +3. Paths that merged cleanly are updated both in the index file and + in your working tree. +4. For conflicting paths, the index file records up to three + versions: stage 1 stores the version from the common ancestor, + stage 2 from `HEAD`, and stage 3 from `MERGE_HEAD` (you + can inspect the stages with `git ls-files -u`). The working + tree files contain the result of the "merge" program; i.e. 3-way + merge results with familiar conflict markers `<<<` `===` `>>>`. +5. No other changes are made. In particular, the local + modifications you had before you started merge will stay the + same and the index entries for them stay as they were, + i.e. matching `HEAD`. -<remote>:: - Other branch head merged into our branch. You need at - least one <remote>. Specifying more than one <remote> - obviously means you are trying an Octopus. +If you tried a merge which resulted in complex conflicts and +want to start over, you can recover with `git merge --abort`. + +HOW CONFLICTS ARE PRESENTED +--------------------------- + +During a merge, the working tree files are updated to reflect the result +of the merge. Among the changes made to the common ancestor's version, +non-overlapping ones (that is, you changed an area of the file while the +other side left that area intact, or vice versa) are incorporated in the +final result verbatim. When both sides made changes to the same area, +however, git cannot randomly pick one side over the other, and asks you to +resolve it by leaving what both sides did to that area. + +By default, git uses the same style as that is used by "merge" program +from the RCS suite to present such a conflicted hunk, like this: + +------------ +Here are lines that are either unchanged from the common +ancestor, or cleanly resolved because only one side changed. +<<<<<<< yours:sample.txt +Conflict resolution is hard; +let's go shopping. +======= +Git makes conflict resolution easy. +>>>>>>> theirs:sample.txt +And here is another line that is cleanly resolved or unmodified. +------------ + +The area where a pair of conflicting changes happened is marked with markers +`<<<<<<<`, `=======`, and `>>>>>>>`. The part before the `=======` +is typically your side, and the part afterwards is typically their side. + +The default format does not show what the original said in the conflicting +area. You cannot tell how many lines are deleted and replaced with +Barbie's remark on your side. The only thing you can tell is that your +side wants to say it is hard and you'd prefer to go shopping, while the +other side wants to claim it is easy. + +An alternative style can be used by setting the "merge.conflictstyle" +configuration variable to "diff3". In "diff3" style, the above conflict +may look like this: + +------------ +Here are lines that are either unchanged from the common +ancestor, or cleanly resolved because only one side changed. +<<<<<<< yours:sample.txt +Conflict resolution is hard; +let's go shopping. +||||||| +Conflict resolution is hard. +======= +Git makes conflict resolution easy. +>>>>>>> theirs:sample.txt +And here is another line that is cleanly resolved or unmodified. +------------ + +In addition to the `<<<<<<<`, `=======`, and `>>>>>>>` markers, it uses +another `|||||||` marker that is followed by the original text. You can +tell that the original just stated a fact, and your side simply gave in to +that statement and gave up, while the other side tried to have a more +positive attitude. You can sometimes come up with a better resolution by +viewing the original. + + +HOW TO RESOLVE CONFLICTS +------------------------ -include::merge-strategies.txt[] +After seeing a conflict, you can do two things: + * Decide not to merge. The only clean-ups you need are to reset + the index file to the `HEAD` commit to reverse 2. and to clean + up working tree changes made by 2. and 3.; `git merge --abort` + can be used for this. -If you tried a merge which resulted in a complex conflicts and -would want to start over, you can recover with -linkgit:git-reset[1]. + * Resolve the conflicts. Git will mark the conflicts in + the working tree. Edit the files into shape and + 'git add' them to the index. Use 'git commit' to seal the deal. -CONFIGURATION -------------- -include::merge-config.txt[] +You can work through the conflict with a number of tools: -branch.<name>.mergeoptions:: - Sets default options for merging into branch <name>. The syntax and - supported options are equal to that of git-merge, but option values - containing whitespace characters are currently not supported. - -HOW MERGE WORKS ---------------- - -A merge is always between the current `HEAD` and one or more -commits (usually, branch head or tag), and the index file must -exactly match the -tree of `HEAD` commit (i.e. the contents of the last commit) when -it happens. In other words, `git-diff --cached HEAD` must -report no changes. - -[NOTE] -This is a bit of a lie. In certain special cases, your index is -allowed to be different from the tree of the `HEAD` commit. The most -notable case is when your `HEAD` commit is already ahead of what -is being merged, in which case your index can have arbitrary -differences from your `HEAD` commit. Also, your index entries -may have differences from your `HEAD` commit that match -the result of a trivial merge (e.g. you received the same patch -from an external source to produce the same result as what you are -merging). For example, if a path did not exist in the common -ancestor and your head commit but exists in the tree you are -merging into your repository, and if you already happen to have -that path exactly in your index, the merge does not have to -fail. - -Otherwise, merge will refuse to do any harm to your repository -(that is, it may fetch the objects from remote, and it may even -update the local branch used to keep track of the remote branch -with `git pull remote rbranch:lbranch`, but your working tree, -`.git/HEAD` pointer and index file are left intact). - -You may have local modifications in the working tree files. In -other words, `git-diff` is allowed to report changes. -However, the merge uses your working tree as the working area, -and in order to prevent the merge operation from losing such -changes, it makes sure that they do not interfere with the -merge. Those complex tables in read-tree documentation define -what it means for a path to "interfere with the merge". And if -your local modifications interfere with the merge, again, it -stops before touching anything. - -So in the above two "failed merge" case, you do not have to -worry about loss of data --- you simply were not ready to do -a merge, so no merge happened at all. You may want to finish -whatever you were in the middle of doing, and retry the same -pull after you are done and ready. - -When things cleanly merge, these things happen: - -1. The results are updated both in the index file and in your - working tree; -2. Index file is written out as a tree; -3. The tree gets committed; and -4. The `HEAD` pointer gets advanced. - -Because of 2., we require that the original state of the index -file to match exactly the current `HEAD` commit; otherwise we -will write out your local changes already registered in your -index file along with the merge result, which is not good. -Because 1. involves only the paths different between your -branch and the remote branch you are pulling from during the -merge (which is typically a fraction of the whole tree), you can -have local modifications in your working tree as long as they do -not overlap with what the merge updates. - -When there are conflicts, these things happen: - -1. `HEAD` stays the same. - -2. Cleanly merged paths are updated both in the index file and - in your working tree. + * Use a mergetool. `git mergetool` to launch a graphical + mergetool which will work you through the merge. -3. For conflicting paths, the index file records up to three - versions; stage1 stores the version from the common ancestor, - stage2 from `HEAD`, and stage3 from the remote branch (you - can inspect the stages with `git-ls-files -u`). The working - tree files have the result of "merge" program; i.e. 3-way - merge result with familiar conflict markers `<<< === >>>`. + * Look at the diffs. `git diff` will show a three-way diff, + highlighting changes from both the `HEAD` and `MERGE_HEAD` + versions. -4. No other changes are done. In particular, the local - modifications you had before you started merge will stay the - same and the index entries for them stay as they were, - i.e. matching `HEAD`. + * Look at the diffs from each branch. `git log --merge -p <path>` + will show diffs first for the `HEAD` version and then the + `MERGE_HEAD` version. -After seeing a conflict, you can do two things: + * Look at the originals. `git show :1:filename` shows the + common ancestor, `git show :2:filename` shows the `HEAD` + version, and `git show :3:filename` shows the `MERGE_HEAD` + version. - * Decide not to merge. The only clean-up you need are to reset - the index file to the `HEAD` commit to reverse 2. and to clean - up working tree changes made by 2. and 3.; `git-reset` can - be used for this. - * Resolve the conflicts. `git-diff` would report only the - conflicting paths because of the above 2. and 3.. Edit the - working tree files into a desirable shape, `git-add` or `git-rm` - them, to make the index file contain what the merge result - should be, and run `git-commit` to commit the result. +EXAMPLES +-------- +* Merge branches `fixes` and `enhancements` on top of + the current branch, making an octopus merge: ++ +------------------------------------------------ +$ git merge fixes enhancements +------------------------------------------------ + +* Merge branch `obsolete` into the current branch, using `ours` + merge strategy: ++ +------------------------------------------------ +$ git merge -s ours obsolete +------------------------------------------------ + +* Merge branch `maint` into the current branch, but do not make + a new commit automatically: ++ +------------------------------------------------ +$ git merge --no-commit maint +------------------------------------------------ ++ +This can be used when you want to include further changes to the +merge, or want to write your own merge commit message. ++ +You should refrain from abusing this option to sneak substantial +changes into a merge commit. Small fixups like bumping +release/version name would be acceptable. -SEE ALSO --------- -linkgit:git-fmt-merge-msg[1], linkgit:git-pull[1], -linkgit:gitattributes[5] +include::merge-strategies.txt[] -Author ------- -Written by Junio C Hamano <junkio@cox.net> +CONFIGURATION +------------- +include::merge-config.txt[] +branch.<name>.mergeoptions:: + Sets default options for merging into branch <name>. The syntax and + supported options are the same as those of 'git merge', but option + values containing whitespace characters are currently not supported. -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. +SEE ALSO +-------- +linkgit:git-fmt-merge-msg[1], linkgit:git-pull[1], +linkgit:gitattributes[5], +linkgit:git-reset[1], +linkgit:git-diff[1], linkgit:git-ls-files[1], +linkgit:git-add[1], linkgit:git-rm[1], +linkgit:git-mergetool[1] GIT --- |