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