| git-merge(1) |
| ============ |
| |
| NAME |
| ---- |
| git-merge - Join two or more development histories together |
| |
| |
| SYNOPSIS |
| -------- |
| [verse] |
| 'git merge' [-n] [--stat] [--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 (`C`). |
| |
| ------------ |
| 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.txt[] |
| |
| -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.txt[] |
| |
| --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.txt[] |
| |
| 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.txt[] |
| |
| include::config/merge.txt[] |
| |
| 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 |