]>
Commit | Line | Data |
---|---|---|
0f69be53 JH |
1 | git-merge(1) |
2 | ============ | |
0f69be53 JH |
3 | |
4 | NAME | |
5 | ---- | |
c3f0baac | 6 | git-merge - Join two or more development histories together |
0f69be53 JH |
7 | |
8 | ||
9 | SYNOPSIS | |
10 | -------- | |
17bcdad3 | 11 | [verse] |
b1889c36 | 12 | 'git merge' [-n] [--stat] [--no-commit] [--squash] [-s <strategy>]... |
1e8b0d48 | 13 | [-m <msg>] <remote> <remote>... |
b1889c36 | 14 | 'git merge' <msg> HEAD <remote>... |
0f69be53 JH |
15 | |
16 | DESCRIPTION | |
17 | ----------- | |
17bcdad3 | 18 | This is the top-level interface to the merge machinery |
0f69be53 JH |
19 | which drives multiple merge strategy scripts. |
20 | ||
dee48c3c JH |
21 | The second syntax (<msg> `HEAD` <remote>) is supported for |
22 | historical reasons. Do not use it from the command line or in | |
23 | new scripts. It is the same as `git merge -m <msg> <remote>`. | |
24 | ||
0f69be53 JH |
25 | |
26 | OPTIONS | |
27 | ------- | |
93d69d86 | 28 | include::merge-options.txt[] |
0f69be53 | 29 | |
dee48c3c | 30 | -m <msg>:: |
3c64314c | 31 | The commit message to be used for the merge commit (in case |
ba020ef5 JN |
32 | it is created). The 'git-fmt-merge-msg' script can be used |
33 | to give a good default for automated 'git-merge' invocations. | |
3c64314c | 34 | |
f448e24e AMS |
35 | <remote>...:: |
36 | Other branch heads to merge into our branch. You need at | |
0f69be53 JH |
37 | least one <remote>. Specifying more than one <remote> |
38 | obviously means you are trying an Octopus. | |
39 | ||
bb73d73c JL |
40 | include::merge-strategies.txt[] |
41 | ||
0f69be53 | 42 | |
3ae854c3 | 43 | If you tried a merge which resulted in a complex conflicts and |
ba020ef5 | 44 | would want to start over, you can recover with 'git-reset'. |
3ae854c3 | 45 | |
dbddb714 JN |
46 | CONFIGURATION |
47 | ------------- | |
f5a84c37 | 48 | include::merge-config.txt[] |
dbddb714 | 49 | |
aec7b362 LH |
50 | branch.<name>.mergeoptions:: |
51 | Sets default options for merging into branch <name>. The syntax and | |
ba020ef5 | 52 | supported options are equal to that of 'git-merge', but option values |
aec7b362 | 53 | containing whitespace characters are currently not supported. |
3ae854c3 | 54 | |
ffb1a4be JH |
55 | HOW MERGE WORKS |
56 | --------------- | |
57 | ||
58 | A merge is always between the current `HEAD` and one or more | |
81646ad2 | 59 | commits (usually, branch head or tag), and the index file must |
c0be8aa0 PB |
60 | match the tree of `HEAD` commit (i.e. the contents of the last commit) |
61 | when it starts out. In other words, `git diff --cached HEAD` must | |
62 | report no changes. (One exception is when the changed index | |
63 | entries are already in the same state that would result from | |
64 | the merge anyway.) | |
65 | ||
66 | Three kinds of merge can happen: | |
67 | ||
68 | * The merged commit is already contained in `HEAD`. This is the | |
69 | simplest case, called "Already up-to-date." | |
70 | ||
71 | * `HEAD` is already contained in the merged commit. This is the | |
72 | most common case especially when involved through 'git pull': | |
73 | you are tracking an upstream repository, committed no local | |
74 | changes and now you want to update to a newer upstream revision. | |
75 | Your `HEAD` (and the index) is updated to at point the merged | |
76 | commit, without creating an extra merge commit. This is | |
77 | called "Fast-forward". | |
78 | ||
79 | * Both the merged commit and `HEAD` are independent and must be | |
80 | tied together by a merge commit that has them both as its parents. | |
81 | The rest of this section describes this "True merge" case. | |
82 | ||
83 | The chosen merge strategy merges the two commits into a single | |
84 | new source tree. | |
ffb1a4be JH |
85 | When things cleanly merge, these things happen: |
86 | ||
434e6ef8 SH |
87 | 1. The results are updated both in the index file and in your |
88 | working tree; | |
89 | 2. Index file is written out as a tree; | |
90 | 3. The tree gets committed; and | |
91 | 4. The `HEAD` pointer gets advanced. | |
ffb1a4be JH |
92 | |
93 | Because of 2., we require that the original state of the index | |
94 | file to match exactly the current `HEAD` commit; otherwise we | |
95 | will write out your local changes already registered in your | |
96 | index file along with the merge result, which is not good. | |
97 | Because 1. involves only the paths different between your | |
98 | branch and the remote branch you are pulling from during the | |
99 | merge (which is typically a fraction of the whole tree), you can | |
100 | have local modifications in your working tree as long as they do | |
101 | not overlap with what the merge updates. | |
102 | ||
103 | When there are conflicts, these things happen: | |
104 | ||
105 | 1. `HEAD` stays the same. | |
106 | ||
107 | 2. Cleanly merged paths are updated both in the index file and | |
108 | in your working tree. | |
109 | ||
3ace1fe3 JH |
110 | 3. For conflicting paths, the index file records up to three |
111 | versions; stage1 stores the version from the common ancestor, | |
112 | stage2 from `HEAD`, and stage3 from the remote branch (you | |
b1889c36 | 113 | can inspect the stages with `git ls-files -u`). The working |
3ace1fe3 JH |
114 | tree files have the result of "merge" program; i.e. 3-way |
115 | merge result with familiar conflict markers `<<< === >>>`. | |
ffb1a4be JH |
116 | |
117 | 4. No other changes are done. In particular, the local | |
118 | modifications you had before you started merge will stay the | |
119 | same and the index entries for them stay as they were, | |
120 | i.e. matching `HEAD`. | |
121 | ||
122 | After seeing a conflict, you can do two things: | |
123 | ||
124 | * Decide not to merge. The only clean-up you need are to reset | |
125 | the index file to the `HEAD` commit to reverse 2. and to clean | |
c0be8aa0 | 126 | up working tree changes made by 2. and 3.; 'git-reset --hard' can |
ffb1a4be JH |
127 | be used for this. |
128 | ||
b1889c36 | 129 | * Resolve the conflicts. `git diff` would report only the |
c0be8aa0 PB |
130 | conflicting paths because of the above 2. and 3. |
131 | Edit the working tree files into a desirable shape | |
132 | ('git mergetool' can ease this task), 'git-add' or 'git-rm' | |
ffb1a4be | 133 | them, to make the index file contain what the merge result |
ba020ef5 | 134 | should be, and run 'git-commit' to commit the result. |
ffb1a4be JH |
135 | |
136 | ||
3c64314c PB |
137 | SEE ALSO |
138 | -------- | |
5162e697 | 139 | linkgit:git-fmt-merge-msg[1], linkgit:git-pull[1], |
483bc4f0 JN |
140 | linkgit:gitattributes[5], |
141 | linkgit:git-reset[1], | |
142 | linkgit:git-diff[1], linkgit:git-ls-files[1], | |
143 | linkgit:git-add[1], linkgit:git-rm[1], | |
144 | linkgit:git-mergetool[1] | |
3c64314c | 145 | |
0f69be53 JH |
146 | Author |
147 | ------ | |
59eb68aa | 148 | Written by Junio C Hamano <gitster@pobox.com> |
0f69be53 JH |
149 | |
150 | ||
151 | Documentation | |
152 | -------------- | |
153 | Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. | |
154 | ||
155 | GIT | |
156 | --- | |
9e1f0a85 | 157 | Part of the linkgit:git[1] suite |