| git-merge(1) |
| ============ |
| |
| NAME |
| ---- |
| git-merge - Join two or more development histories together |
| |
| |
| SYNOPSIS |
| -------- |
| [verse] |
| 'git merge' [-n] [--stat] [--no-commit] [--squash] [--[no-]edit] |
| [-s <strategy>] [-X <strategy-option>] [-S[<keyid>]] |
| [--[no-]rerere-autoupdate] [-m <msg>] [<commit>...] |
| 'git merge' <msg> HEAD <commit>... |
| 'git merge' --abort |
| |
| 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. |
| |
| ------------ |
| 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> <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 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 |
| ------- |
| include::merge-options.txt[] |
| |
| -S[<keyid>]:: |
| --gpg-sign[=<keyid>]:: |
| GPG-sign the resulting merge commit. The `keyid` argument is |
| optional and defaults to the committer identity; if specified, |
| it must be stuck to the option without a space. |
| |
| -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. |
| |
| --[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, 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. (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`. |
| |
| 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. |
| <<<<<<< 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 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' 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 `MERGE_HEAD` |
| versions. |
| |
| * 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 |
| ------------- |
| 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. |
| |
| 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 |