mirror of
https://github.com/git/git
synced 2024-08-27 11:39:22 +00:00
Documentation: simplify How Merge Works
The user most likely does not care about the exact order of operations because he cannot see it happening anyway. Instead, try to explain what it means to merge two commits into a single tree. While at it: - Change the heading to TRUE MERGE. The entire manual page is about how merges work. - Document MERGE_HEAD. It is a useful feature, since it makes the parents of the intended merge commit easier to refer to. - Do not assume commits named on the 'git merge' command line come from another repository. For simplicity, the discussion of conflicts still does assume that there is only one and it is a branch head. - Do not start list items with `code`. Otherwise, a toolchain bug produces a line break in the generated nroff, resulting in odd extra space. Suggested-by: Thomas Rast <trast@student.ethz.ch> Signed-off-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Thomas Rast <trast@student.ethz.ch>
This commit is contained in:
parent
29280311f0
commit
ebef7e5049
|
@ -100,52 +100,32 @@ merge commit.
|
||||||
|
|
||||||
This behavior can be suppressed with the `--no-ff` option.
|
This behavior can be suppressed with the `--no-ff` option.
|
||||||
|
|
||||||
HOW MERGE WORKS
|
TRUE MERGE
|
||||||
---------------
|
----------
|
||||||
|
|
||||||
A merge is always between the current `HEAD` and one or more
|
|
||||||
commits (usually a branch head or tag).
|
|
||||||
|
|
||||||
Except in a fast-forward merge (see above), the branches to be
|
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
|
merged must be tied together by a merge commit that has both of them
|
||||||
as its parents.
|
as its parents.
|
||||||
The rest of this section describes this "True merge" case.
|
|
||||||
|
|
||||||
The chosen merge strategy merges the two commits into a single
|
A merged version reconciling the changes from all branches to be
|
||||||
new source tree.
|
merged is committed, and your `HEAD`, index, and working tree are
|
||||||
When things merge cleanly, this is what happens:
|
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.
|
||||||
|
|
||||||
1. The results are updated both in the index file and in your
|
When it is not obvious how to reconcile the changes, the following
|
||||||
working tree;
|
happens:
|
||||||
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
|
1. The `HEAD` pointer stays the same.
|
||||||
file matches exactly the current `HEAD` commit; otherwise we
|
2. The `MERGE_HEAD` ref is set to point to the other branch head.
|
||||||
will write out your local changes already registered in your
|
3. Paths that merged cleanly are updated both in the index file and
|
||||||
index file along with the merge result, which is not good.
|
|
||||||
Because 1. involves only those paths differing between your
|
|
||||||
branch and the branch you are merging
|
|
||||||
(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.
|
in your working tree.
|
||||||
|
4. For conflicting paths, the index file records up to three
|
||||||
3. For conflicting paths, the index file records up to three
|
versions: stage 1 stores the version from the common ancestor,
|
||||||
versions; stage1 stores the version from the common ancestor,
|
stage 2 from `HEAD`, and stage 3 from `MERGE_HEAD` (you
|
||||||
stage2 from `HEAD`, and stage3 from the other branch (you
|
|
||||||
can inspect the stages with `git ls-files -u`). The working
|
can inspect the stages with `git ls-files -u`). The working
|
||||||
tree files contain the result of the "merge" program; i.e. 3-way
|
tree files contain the result of the "merge" program; i.e. 3-way
|
||||||
merge results with familiar conflict markers `<<< === >>>`.
|
merge results with familiar conflict markers `<<<` `===` `>>>`.
|
||||||
|
5. No other changes are made. In particular, the local
|
||||||
4. No other changes are done. In particular, the local
|
|
||||||
modifications you had before you started merge will stay the
|
modifications you had before you started merge will stay the
|
||||||
same and the index entries for them stay as they were,
|
same and the index entries for them stay as they were,
|
||||||
i.e. matching `HEAD`.
|
i.e. matching `HEAD`.
|
||||||
|
|
Loading…
Reference in a new issue