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