diff options
Diffstat (limited to 'Documentation/git-merge.txt')
| -rw-r--r-- | Documentation/git-merge.txt | 157 |
1 files changed, 157 insertions, 0 deletions
diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt new file mode 100644 index 0000000000..17a15acb07 --- /dev/null +++ b/Documentation/git-merge.txt @@ -0,0 +1,157 @@ +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> <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>:: + The commit message to be used for the merge commit (in case + it is created). The 'git-fmt-merge-msg' script 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 a complex conflicts and +would 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 equal to that 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 involved through 'git pull': + you are tracking an upstream repository, committed no local + changes and now you want to update to a newer upstream revision. + Your `HEAD` (and the index) is updated to at point 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 them both 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 cleanly merge, these things happen: + +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 to match 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 the paths different 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, these things happen: + +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 have the result of "merge" program; i.e. 3-way + merge result 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`. + +After seeing a conflict, you can do two things: + + * Decide not to merge. The only clean-up 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 diff` would report only the + conflicting paths because of the above 2. and 3. + Edit the working tree files into a desirable shape + ('git mergetool' can ease this task), 'git-add' or 'git-rm' + them, to make the index file contain what the merge result + should be, and run 'git-commit' to commit the result. + + +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 |