]>
Commit | Line | Data |
---|---|---|
0f69be53 JH |
1 | git-merge(1) |
2 | ============ | |
0f69be53 JH |
3 | |
4 | NAME | |
5 | ---- | |
6 | git-merge - Grand Unified Merge Driver | |
7 | ||
8 | ||
9 | SYNOPSIS | |
10 | -------- | |
37465016 | 11 | 'git-merge' [-n] [--no-commit] [-s <strategy>]... <msg> <head> <remote> <remote>... |
0f69be53 JH |
12 | |
13 | ||
14 | DESCRIPTION | |
15 | ----------- | |
16 | This is the top-level user interface to the merge machinery | |
17 | which drives multiple merge strategy scripts. | |
18 | ||
19 | ||
20 | OPTIONS | |
21 | ------- | |
93d69d86 | 22 | include::merge-options.txt[] |
0f69be53 | 23 | |
3c64314c PB |
24 | <msg>:: |
25 | The commit message to be used for the merge commit (in case | |
26 | it is created). The `git-fmt-merge-msg` script can be used | |
27 | to give a good default for automated `git-merge` invocations. | |
28 | ||
0f69be53 JH |
29 | <head>:: |
30 | our branch head commit. | |
31 | ||
32 | <remote>:: | |
33 | other branch head merged into our branch. You need at | |
34 | least one <remote>. Specifying more than one <remote> | |
35 | obviously means you are trying an Octopus. | |
36 | ||
bb73d73c JL |
37 | include::merge-strategies.txt[] |
38 | ||
0f69be53 | 39 | |
3ae854c3 JH |
40 | If you tried a merge which resulted in a complex conflicts and |
41 | would want to start over, you can recover with | |
42 | gitlink:git-reset[1]. | |
43 | ||
44 | ||
ffb1a4be JH |
45 | HOW MERGE WORKS |
46 | --------------- | |
47 | ||
48 | A merge is always between the current `HEAD` and one or more | |
49 | remote branch heads, and the index file must exactly match the | |
50 | tree of `HEAD` commit (i.e. the contents of the last commit) when | |
51 | it happens. In other words, `git-diff --cached HEAD` must | |
52 | report no changes. | |
53 | ||
54 | [NOTE] | |
55 | This is a bit of lie. In certain special cases, your index are | |
56 | allowed to be different from the tree of `HEAD` commit. The most | |
57 | notable case is when your `HEAD` commit is already ahead of what | |
58 | is being merged, in which case your index can have arbitrary | |
59 | difference from your `HEAD` commit. Otherwise, your index entries | |
60 | are allowed have differences from your `HEAD` commit that match | |
61 | the result of trivial merge (e.g. you received the same patch | |
62 | from external source to produce the same result as what you are | |
63 | merging). For example, if a path did not exist in the common | |
64 | ancestor and your head commit but exists in the tree you are | |
65 | merging into your repository, and if you already happen to have | |
66 | that path exactly in your index, the merge does not have to | |
67 | fail. | |
68 | ||
69 | Otherwise, merge will refuse to do any harm to your repository | |
70 | (that is, it may fetch the objects from remote, and it may even | |
71 | update the local branch used to keep track of the remote branch | |
72 | with `git pull remote rbranch:lbranch`, but your working tree, | |
73 | `.git/HEAD` pointer and index file are left intact). | |
74 | ||
75 | You may have local modifications in the working tree files. In | |
76 | other words, `git-diff` is allowed to report changes. | |
77 | However, the merge uses your working tree as the working area, | |
78 | and in order to prevent the merge operation from losing such | |
79 | changes, it makes sure that they do not interfere with the | |
80 | merge. Those complex tables in read-tree documentation define | |
81 | what it means for a path to "interfere with the merge". And if | |
82 | your local modifications interfere with the merge, again, it | |
83 | stops before touching anything. | |
84 | ||
85 | So in the above two "failed merge" case, you do not have to | |
86 | worry about lossage of data --- you simply were not ready to do | |
87 | a merge, so no merge happened at all. You may want to finish | |
88 | whatever you were in the middle of doing, and retry the same | |
89 | pull after you are done and ready. | |
90 | ||
91 | When things cleanly merge, these things happen: | |
92 | ||
93 | 1. the results are updated both in the index file and in your | |
94 | working tree, | |
95 | 2. index file is written out as a tree, | |
96 | 3. the tree gets committed, and | |
97 | 4. the `HEAD` pointer gets advanced. | |
98 | ||
99 | Because of 2., we require that the original state of the index | |
100 | file to match exactly the current `HEAD` commit; otherwise we | |
101 | will write out your local changes already registered in your | |
102 | index file along with the merge result, which is not good. | |
103 | Because 1. involves only the paths different between your | |
104 | branch and the remote branch you are pulling from during the | |
105 | merge (which is typically a fraction of the whole tree), you can | |
106 | have local modifications in your working tree as long as they do | |
107 | not overlap with what the merge updates. | |
108 | ||
109 | When there are conflicts, these things happen: | |
110 | ||
111 | 1. `HEAD` stays the same. | |
112 | ||
113 | 2. Cleanly merged paths are updated both in the index file and | |
114 | in your working tree. | |
115 | ||
3ace1fe3 JH |
116 | 3. For conflicting paths, the index file records up to three |
117 | versions; stage1 stores the version from the common ancestor, | |
118 | stage2 from `HEAD`, and stage3 from the remote branch (you | |
119 | can inspect the stages with `git-ls-files -u`). The working | |
120 | tree files have the result of "merge" program; i.e. 3-way | |
121 | merge result with familiar conflict markers `<<< === >>>`. | |
ffb1a4be JH |
122 | |
123 | 4. No other changes are done. In particular, the local | |
124 | modifications you had before you started merge will stay the | |
125 | same and the index entries for them stay as they were, | |
126 | i.e. matching `HEAD`. | |
127 | ||
128 | After seeing a conflict, you can do two things: | |
129 | ||
130 | * Decide not to merge. The only clean-up you need are to reset | |
131 | the index file to the `HEAD` commit to reverse 2. and to clean | |
132 | up working tree changes made by 2. and 3.; `git-reset` can | |
133 | be used for this. | |
134 | ||
135 | * Resolve the conflicts. `git-diff` would report only the | |
136 | conflicting paths because of the above 2. and 3.. Edit the | |
137 | working tree files into a desirable shape, `git-update-index` | |
138 | them, to make the index file contain what the merge result | |
139 | should be, and run `git-commit` to commit the result. | |
140 | ||
141 | ||
3c64314c PB |
142 | SEE ALSO |
143 | -------- | |
fdd08979 | 144 | gitlink:git-fmt-merge-msg[1], gitlink:git-pull[1] |
3c64314c PB |
145 | |
146 | ||
0f69be53 JH |
147 | Author |
148 | ------ | |
149 | Written by Junio C Hamano <junkio@cox.net> | |
150 | ||
151 | ||
152 | Documentation | |
153 | -------------- | |
154 | Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. | |
155 | ||
156 | GIT | |
157 | --- | |
a7154e91 | 158 | Part of the gitlink:git[7] suite |