| git-merge(1) |
| ============ |
| |
| NAME |
| ---- |
| git-merge - Join two or more development histories together |
| |
| |
| SYNOPSIS |
| -------- |
| [verse] |
| 'git merge' [-n] [--stat] [--no-commit] [--squash] [-s <strategy>]... |
| [-m <msg>] <remote>... |
| 'git merge' <msg> HEAD <remote>... |
| |
| 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 |
| historical reasons. Do not use it from the command line or in |
| new scripts. It is the same as `git merge -m <msg> <remote>`. |
| |
| |
| OPTIONS |
| ------- |
| include::merge-options.txt[] |
| |
| -m <msg>:: |
| Set the commit message to be used for the merge commit (in |
| case one is created). The 'git fmt-merge-msg' command can be |
| used to give a good default for automated 'git merge' |
| invocations. |
| |
| <remote>...:: |
| Other branch heads to merge into our branch. You need at |
| least one <remote>. Specifying more than one <remote> |
| obviously means you are trying an Octopus. |
| |
| include::merge-strategies.txt[] |
| |
| |
| If you tried a merge which resulted in complex conflicts and |
| want to start over, you can recover with 'git-reset'. |
| |
| 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. |
| |
| 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 |
| match the tree of `HEAD` commit (i.e. the contents of the last commit) |
| when it starts out. In other words, `git diff --cached HEAD` must |
| report no changes. (One exception is when the changed index |
| entries are already in the same state that would result from |
| the merge anyway.) |
| |
| Three kinds of merge can happen: |
| |
| * The merged commit is already contained in `HEAD`. This is the |
| simplest case, called "Already up-to-date." |
| |
| * `HEAD` is already contained in the merged commit. This is the |
| most common case especially when invoked from 'git pull': |
| you are tracking an upstream repository, have committed no local |
| changes and now you want to update to a newer upstream revision. |
| Your `HEAD` (and the index) is updated to point at the merged |
| commit, without creating an extra merge commit. This is |
| called "Fast-forward". |
| |
| * Both the merged commit and `HEAD` are independent and must be |
| tied together by a merge commit that has both of them as its parents. |
| The rest of this section describes this "True merge" case. |
| |
| The chosen merge strategy merges the two commits into a single |
| new source tree. |
| When things merge cleanly, this is what happens: |
| |
| 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 matches 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 those paths differing 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, the following happens: |
| |
| 1. `HEAD` stays the same. |
| |
| 2. Cleanly merged paths are updated both in the index file and |
| in your working tree. |
| |
| 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 contain the result of the "merge" program; i.e. 3-way |
| merge results with familiar conflict markers `<<< === >>>`. |
| |
| 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`. |
| |
| 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 |
| ------------------------ |
| |
| 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-reset --hard' 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' to seal the deal. |
| |
| You can work through the conflict with a number of tools: |
| |
| * Use a mergetool. 'git mergetool' to launch a graphical |
| mergetool which will work you through the merge. |
| |
| * Look at the diffs. 'git diff' will show a three-way diff, |
| highlighting changes from both the HEAD and remote versions. |
| |
| * Look at the diffs on their own. 'git log --merge -p <path>' |
| will show diffs first for the HEAD version and then the |
| remote 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 remote version. |
| |
| 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] |
| |
| Author |
| ------ |
| Written by Junio C Hamano <gitster@pobox.com> |
| |
| |
| Documentation |
| -------------- |
| Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. |
| |
| GIT |
| --- |
| Part of the linkgit:git[1] suite |
