294 lines
10 KiB
Plaintext
294 lines
10 KiB
Plaintext
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`. See linkgit:gitmergeconflicts[7]
|
|
(or `git help mergeconflicts`) for a guide to handling merge 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
|
|
-------
|
|
: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
|
|
----
|
|
|
|
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]
|
|
linkgit:gitmergeconflicts[7]
|
|
|
|
GIT
|
|
---
|
|
Part of the linkgit:git[1] suite
|