diff options
Diffstat (limited to 'Documentation/git-merge.adoc')
| -rw-r--r-- | Documentation/git-merge.adoc | 412 |
1 files changed, 412 insertions, 0 deletions
diff --git a/Documentation/git-merge.adoc b/Documentation/git-merge.adoc new file mode 100644 index 0000000000..a055384ad6 --- /dev/null +++ b/Documentation/git-merge.adoc @@ -0,0 +1,412 @@ +git-merge(1) +============ + +NAME +---- +git-merge - Join two or more development histories together + + +SYNOPSIS +-------- +[synopsis] +git merge [-n] [--stat] [--compact-summary] [--no-commit] [--squash] [--[no-]edit] + [--no-verify] [-s <strategy>] [-X <strategy-option>] [-S[<keyid>]] + [--[no-]allow-unrelated-histories] + [--[no-]rerere-autoupdate] [-m <msg>] [-F <file>] + [--into-name <branch>] [<commit>...] +git merge (--continue | --abort | --quit) + +DESCRIPTION +----------- +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. Before the operation, +`ORIG_HEAD` is set to the tip of the current branch (`G`). + +------------ + A---B---C topic + / \ + D---E---F---G---H master +------------ + +A merge stops if there's a conflict that cannot be resolved +automatically or if `--no-commit` was provided when initiating the +merge. At that point you can run `git merge --abort` or `git merge +--continue`. + +`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 non-trivial uncommitted changes is +discouraged: while possible, it may leave you in a state that is hard to +back out of in the case of a conflict. + +OPTIONS +------- +:git-merge: 1 + +include::merge-options.adoc[] + +`-m <msg>`:: + 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. The automated message can include the branch description. + +`--into-name <branch>`:: + Prepare the default merge message as if merging to the branch + _<branch>_, instead of the name of the real branch to which + the merge is made. + +`-F <file>`:: +`--file=<file>`:: + Read 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. + +include::rerere-options.adoc[] + +`--overwrite-ignore`:: +`--no-overwrite-ignore`:: + Silently overwrite ignored files from the merge result. This + is the default behavior. Use `--no-overwrite-ignore` to abort. + +`--abort`:: + Abort the current conflict resolution process, and + try to reconstruct the pre-merge state. If an autostash entry is + present, apply it to the worktree. ++ +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 unless `MERGE_AUTOSTASH` is also present in +which case `git merge --abort` applies the stash entry to the worktree +whereas `git reset --merge` will save the stashed changes in the stash +list. + +`--quit`:: + Forget about the current merge in progress. Leave the index + and the working tree as-is. If `MERGE_AUTOSTASH` is present, the + stash entry will be saved to the stash list. + +`--continue`:: + After a `git merge` stops due to conflicts you can conclude the + merge by running `git merge --continue` (see "HOW TO RESOLVE + CONFLICTS" section below). + +`<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, 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. ++ +When `FETCH_HEAD` (and no other commit) is specified, the branches +recorded in the `.git/FETCH_HEAD` file by the previous invocation +of `git fetch` for merging are merged to the current branch. + + +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. (Special +narrow exceptions to this rule may exist depending on which merge +strategy is in use, but generally, the index must match `HEAD`.) + +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 operation; i.e. 3-way + merge results with familiar conflict markers +<<<+ `===` +>>>+. +5. A ref named `AUTO_MERGE` is written, pointing to a tree + corresponding to the current content of the working tree (including + conflict markers for textual conflicts). Note that this ref is only + written when the `ort` merge strategy is used (the default). +6. 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`. + +If you tried a merge which resulted in complex conflicts and +want to start over, you can recover with `git merge --abort`. + +MERGING TAG +----------- + +When merging an annotated (and possibly signed) tag, Git always +creates a merge commit even if a fast-forward merge is possible, and +the commit message template is prepared with the tag message. +Additionally, if the tag is signed, the signature check is reported +as a comment in the message template. See also linkgit:git-tag[1]. + +When you want to just integrate with the work leading to the commit +that happens to be tagged, e.g. synchronizing with an upstream +release point, you may not want to make an unnecessary merge commit. + +In such a case, you can "unwrap" the tag yourself before feeding it +to `git merge`, or pass `--ff-only` when you do not have any work on +your own. e.g. + +---- +git fetch origin +git merge v1.2.3^0 +git merge --ff-only v1.2.3 +---- + +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 the one used by the "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, +or cleanly resolved because both sides changed the same way. +<<<<<<< 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 either `diff3` or `zdiff3`. 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 +or cleanly resolved because both sides changed the same way. +Conflict resolution is hard; +let's go shopping. +||||||| base:sample.txt +or cleanly resolved because both sides changed identically. +Conflict resolution is hard. +======= +or cleanly resolved because both sides changed the same way. +Git makes conflict resolution easy. +>>>>>>> theirs:sample.txt +And here is another line that is cleanly resolved or unmodified. +------------ + +while in `zdiff3` style, it may look like this: + +------------ +Here are lines that are either unchanged from the common +ancestor, or cleanly resolved because only one side changed, +or cleanly resolved because both sides changed the same way. +<<<<<<< yours:sample.txt +Conflict resolution is hard; +let's go shopping. +||||||| base:sample.txt +or cleanly resolved because both sides changed identically. +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 +------------------------ + +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. + + * 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` or + `git merge --continue` to seal the deal. The latter command + checks whether there is a (interrupted) merge in progress + before calling `git commit`. + +You can work through the conflict with a number of tools: + + * Use a mergetool. `git mergetool` to launch a graphical + mergetool which will work through the merge with you. + + * Look at the diffs. `git diff` will show a three-way diff, + highlighting changes from both the `HEAD` and `MERGE_HEAD` + versions. `git diff AUTO_MERGE` will show what changes you've + made so far to resolve textual conflicts. + + * 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. + + * 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. + + +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. + + +include::merge-strategies.adoc[] + +CONFIGURATION +------------- + +`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. + +include::includes/cmd-config-section-rest.adoc[] + +include::config/merge.adoc[] + +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 +--- +Part of the linkgit:git[1] suite |