]>
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 PB |
31 | The commit message to be used for the merge commit (in case |
32 | it is created). The `git-fmt-merge-msg` script can be used | |
33 | to give a good default for automated `git-merge` invocations. | |
34 | ||
0f69be53 | 35 | <remote>:: |
17bcdad3 | 36 | Other branch head merged 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 JH |
43 | If you tried a merge which resulted in a complex conflicts and |
44 | would want to start over, you can recover with | |
5162e697 | 45 | linkgit:git-reset[1]. |
3ae854c3 | 46 | |
dbddb714 JN |
47 | CONFIGURATION |
48 | ------------- | |
f5a84c37 | 49 | include::merge-config.txt[] |
dbddb714 | 50 | |
aec7b362 LH |
51 | branch.<name>.mergeoptions:: |
52 | Sets default options for merging into branch <name>. The syntax and | |
53 | supported options are equal to that of git-merge, but option values | |
54 | containing whitespace characters are currently not supported. | |
3ae854c3 | 55 | |
ffb1a4be JH |
56 | HOW MERGE WORKS |
57 | --------------- | |
58 | ||
59 | A merge is always between the current `HEAD` and one or more | |
81646ad2 MM |
60 | commits (usually, branch head or tag), and the index file must |
61 | exactly match the | |
ffb1a4be | 62 | tree of `HEAD` commit (i.e. the contents of the last commit) when |
b1889c36 | 63 | it happens. In other words, `git diff --cached HEAD` must |
ffb1a4be JH |
64 | report no changes. |
65 | ||
66 | [NOTE] | |
b98525e4 DP |
67 | This is a bit of a lie. In certain special cases, your index is |
68 | allowed to be different from the tree of the `HEAD` commit. The most | |
ffb1a4be JH |
69 | notable case is when your `HEAD` commit is already ahead of what |
70 | is being merged, in which case your index can have arbitrary | |
b98525e4 DP |
71 | differences from your `HEAD` commit. Also, your index entries |
72 | may have differences from your `HEAD` commit that match | |
73 | the result of a trivial merge (e.g. you received the same patch | |
74 | from an external source to produce the same result as what you are | |
ffb1a4be JH |
75 | merging). For example, if a path did not exist in the common |
76 | ancestor and your head commit but exists in the tree you are | |
77 | merging into your repository, and if you already happen to have | |
78 | that path exactly in your index, the merge does not have to | |
79 | fail. | |
80 | ||
81 | Otherwise, merge will refuse to do any harm to your repository | |
82 | (that is, it may fetch the objects from remote, and it may even | |
83 | update the local branch used to keep track of the remote branch | |
84 | with `git pull remote rbranch:lbranch`, but your working tree, | |
85 | `.git/HEAD` pointer and index file are left intact). | |
86 | ||
87 | You may have local modifications in the working tree files. In | |
88 | other words, `git-diff` is allowed to report changes. | |
89 | However, the merge uses your working tree as the working area, | |
90 | and in order to prevent the merge operation from losing such | |
91 | changes, it makes sure that they do not interfere with the | |
92 | merge. Those complex tables in read-tree documentation define | |
93 | what it means for a path to "interfere with the merge". And if | |
94 | your local modifications interfere with the merge, again, it | |
95 | stops before touching anything. | |
96 | ||
97 | So in the above two "failed merge" case, you do not have to | |
addf88e4 | 98 | worry about loss of data --- you simply were not ready to do |
ffb1a4be JH |
99 | a merge, so no merge happened at all. You may want to finish |
100 | whatever you were in the middle of doing, and retry the same | |
101 | pull after you are done and ready. | |
102 | ||
103 | When things cleanly merge, these things happen: | |
104 | ||
434e6ef8 SH |
105 | 1. The results are updated both in the index file and in your |
106 | working tree; | |
107 | 2. Index file is written out as a tree; | |
108 | 3. The tree gets committed; and | |
109 | 4. The `HEAD` pointer gets advanced. | |
ffb1a4be JH |
110 | |
111 | Because of 2., we require that the original state of the index | |
112 | file to match exactly the current `HEAD` commit; otherwise we | |
113 | will write out your local changes already registered in your | |
114 | index file along with the merge result, which is not good. | |
115 | Because 1. involves only the paths different between your | |
116 | branch and the remote branch you are pulling from during the | |
117 | merge (which is typically a fraction of the whole tree), you can | |
118 | have local modifications in your working tree as long as they do | |
119 | not overlap with what the merge updates. | |
120 | ||
121 | When there are conflicts, these things happen: | |
122 | ||
123 | 1. `HEAD` stays the same. | |
124 | ||
125 | 2. Cleanly merged paths are updated both in the index file and | |
126 | in your working tree. | |
127 | ||
3ace1fe3 JH |
128 | 3. For conflicting paths, the index file records up to three |
129 | versions; stage1 stores the version from the common ancestor, | |
130 | stage2 from `HEAD`, and stage3 from the remote branch (you | |
b1889c36 | 131 | can inspect the stages with `git ls-files -u`). The working |
3ace1fe3 JH |
132 | tree files have the result of "merge" program; i.e. 3-way |
133 | merge result with familiar conflict markers `<<< === >>>`. | |
ffb1a4be JH |
134 | |
135 | 4. No other changes are done. In particular, the local | |
136 | modifications you had before you started merge will stay the | |
137 | same and the index entries for them stay as they were, | |
138 | i.e. matching `HEAD`. | |
139 | ||
140 | After seeing a conflict, you can do two things: | |
141 | ||
142 | * Decide not to merge. The only clean-up you need are to reset | |
143 | the index file to the `HEAD` commit to reverse 2. and to clean | |
144 | up working tree changes made by 2. and 3.; `git-reset` can | |
145 | be used for this. | |
146 | ||
b1889c36 | 147 | * Resolve the conflicts. `git diff` would report only the |
ffb1a4be | 148 | conflicting paths because of the above 2. and 3.. Edit the |
d7f078b8 | 149 | working tree files into a desirable shape, `git-add` or `git-rm` |
ffb1a4be JH |
150 | them, to make the index file contain what the merge result |
151 | should be, and run `git-commit` to commit the result. | |
152 | ||
153 | ||
3c64314c PB |
154 | SEE ALSO |
155 | -------- | |
5162e697 DM |
156 | linkgit:git-fmt-merge-msg[1], linkgit:git-pull[1], |
157 | linkgit:gitattributes[5] | |
3c64314c PB |
158 | |
159 | ||
0f69be53 JH |
160 | Author |
161 | ------ | |
162 | Written by Junio C Hamano <junkio@cox.net> | |
163 | ||
164 | ||
165 | Documentation | |
166 | -------------- | |
167 | Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. | |
168 | ||
169 | GIT | |
170 | --- | |
9e1f0a85 | 171 | Part of the linkgit:git[1] suite |