1GIT-MERGE(1) Git Manual GIT-MERGE(1)
2
6 git-merge - Join two or more development histories together
7
9 git-merge [-n] [--summary] [--no-commit] [--squash] [-s <strategy>]...
10 [-m <msg>] <remote> <remote>...
11
13 This is the top-level interface to the merge machinery which drives
14 multiple merge strategy scripts.
15
17 --summary
18 Show a diffstat at the end of the merge. The diffstat is also
19 controlled by the configuration option merge.diffstat.
20 -n, --no-summary
22 Do not show diffstat at the end of the merge.
23 --no-commit
25 Perform the merge but pretend the merge failed and do not
26 autocommit, to give the user a chance to inspect and further tweak
27 the merge result before committing.
28 --squash
30 Produce the working tree and index state as if a real merge
31 happened, but do not actually make a commit or move the HEAD, nor
32 record $GIT_DIR/MERGE_HEAD to cause the next git commit command to
33 create a merge commit. This allows you to create a single commit on
34 top of the current branch whose effect is the same as merging
35 another branch (or more in case of an octopus).
36 -s <strategy>, --strategy=<strategy>
38 Use the given merge strategy; can be supplied more than once to
39 specify them in the order they should be tried. If there is no -s
40 option, a built-in list of strategies is used instead
41 (git-merge-recursive when merging a single head, git-merge-octopus
42 otherwise).
43 <msg>
45 The commit message to be used for the merge commit (in case it is
46 created). The git-fmt-merge-msg script can be used to give a good
47 default for automated git-merge invocations.
48 <head>
50 Our branch head commit. This has to be HEAD, so new syntax does not
51 require it
52 <remote>
54 Other branch head merged into our branch. You need at least one
55 <remote>. Specifying more than one <remote> obviously means you are
56 trying an Octopus.
57
59 resolve
60 This can only resolve two heads (i.e. the current branch and
61 another branch you pulled from) using 3-way merge algorithm. It
62 tries to carefully detect criss-cross merge ambiguities and is
63 considered generally safe and fast.
64 recursive
66 This can only resolve two heads using 3-way merge algorithm. When
67 there are more than one common ancestors that can be used for 3-way
68 merge, it creates a merged tree of the common ancestors and uses
69 that as the reference tree for the 3-way merge. This has been
70 reported to result in fewer merge conflicts without causing
71 mis-merges by tests done on actual merge commits taken from Linux
72 2.6 kernel development history. Additionally this can detect and
73 handle merges involving renames. This is the default merge strategy
74 when pulling or merging one branch.
75 octopus
77 This resolves more than two-head case, but refuses to do complex
78 merge that needs manual resolution. It is primarily meant to be
79 used for bundling topic branch heads together. This is the default
80 merge strategy when pulling or merging more than one branches.
81 ours
83 This resolves any number of heads, but the result of the merge is
84 always the current branch head. It is meant to be used to supersede
85 old development history of side branches.
86 If you tried a merge which resulted in a complex conflicts and would
87 want to start over, you can recover with git-reset(1).
88
90 merge.summary
91 Whether to include summaries of merged commits in newly created
92 merge commit. False by default.
93 merge.verbosity
95 Controls the amount of output shown by the recursive merge
96 strategy. Level 0 outputs nothing except a final error message if
97 conflicts were detected. Level 1 outputs only conflicts, 2 outputs
98 conflicts and file changes. Level 5 and above outputs debugging
99 information. The default is level 2. Can be overridden by
100 GIT_MERGE_VERBOSITY environment variable.
101
103 A merge is always between the current HEAD and one or more remote
104 branch heads, and the index file must exactly match the tree of HEAD
105 commit (i.e. the contents of the last commit) when it happens. In other
106 words, git-diff --cached HEAD must report no changes.
107 Note
109 This is a bit of lie. In certain special cases, your index are allowed
110 to be different from the tree of HEAD commit. The most notable case is
111 when your HEAD commit is already ahead of what is being merged, in
112 which case your index can have arbitrary difference from your HEAD
113 commit. Otherwise, your index entries are allowed have differences from
114 your HEAD commit that match the result of trivial merge (e.g. you
115 received the same patch from external source to produce the same result
116 as what you are merging). For example, if a path did not exist in the
117 common ancestor and your head commit but exists in the tree you are
118 merging into your repository, and if you already happen to have that
119 path exactly in your index, the merge does not have to fail.
120 Otherwise, merge will refuse to do any harm to your repository (that
123 is, it may fetch the objects from remote, and it may even update the
124 local branch used to keep track of the remote branch with git pull
125 remote rbranch:lbranch, but your working tree, .git/HEAD pointer and
126 index file are left intact).
127 You may have local modifications in the working tree files. In other
129 words, git-diff is allowed to report changes. However, the merge uses
130 your working tree as the working area, and in order to prevent the
131 merge operation from losing such changes, it makes sure that they do
132 not interfere with the merge. Those complex tables in read-tree
133 documentation define what it means for a path to "interfere with the
134 merge". And if your local modifications interfere with the merge,
135 again, it stops before touching anything.
136 So in the above two "failed merge" case, you do not have to worry about
138 loss of data --- you simply were not ready to do a merge, so no merge
139 happened at all. You may want to finish whatever you were in the middle
140 of doing, and retry the same pull after you are done and ready.
141 When things cleanly merge, these things happen:
143 1. The results are updated both in the index file and in your working
146 tree;
147 2. Index file is written out as a tree;
149 3. The tree gets committed; and
151 4. The HEAD pointer gets advanced.
153 Because of 2., we require that the original state of the index file to
154 match exactly the current HEAD commit; otherwise we will write out your
155 local changes already registered in your index file along with the
156 merge result, which is not good. Because 1. involves only the paths
157 different between your branch and the remote branch you are pulling
158 from during the merge (which is typically a fraction of the whole
159 tree), you can have local modifications in your working tree as long as
160 they do not overlap with what the merge updates.
161 When there are conflicts, these things happen:
163 1. HEAD stays the same.
166 2. Cleanly merged paths are updated both in the index file and in
168 your working tree.
169 3. For conflicting paths, the index file records up to three
171 versions; stage1 stores the version from the common ancestor,
172 stage2 from HEAD, and stage3 from the remote branch (you can
173 inspect the stages with git-ls-files -u). The working tree files
174 have the result of "merge" program; i.e. 3-way merge result with
175 familiar conflict markers <<< === >>>.
176 4. No other changes are done. In particular, the local modifications
178 you had before you started merge will stay the same and the index
179 entries for them stay as they were, i.e. matching HEAD.
180 After seeing a conflict, you can do two things:
181 · Decide not to merge. The only clean-up you need are to reset the
184 index file to the HEAD commit to reverse 2. and to clean up working
185 tree changes made by 2. and 3.; git-reset can be used for this.
186 · Resolve the conflicts. git-diff would report only the conflicting
188 paths because of the above 2. and 3.. Edit the working tree files
189 into a desirable shape, git-add or git-rm them, to make the index
190 file contain what the merge result should be, and run git-commit to
191 commit the result.
192
194 git-fmt-merge-msg(1), git-pull(1)
195
197 Written by Junio C Hamano <junkio@cox.net>
198
200 Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
201
203 Part of the git(7) suite
204Git 1.5.3.3 10/09/2007 GIT-MERGE(1)