Merge branch 'lt/case-insensitive'
[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] [--stat] [--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 include::merge-config.txt[]
50
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.
55
56 HOW MERGE WORKS
57 ---------------
58
59 A merge is always between the current `HEAD` and one or more
60 commits (usually, branch head or tag), and the index file must
61 exactly match the
62 tree of `HEAD` commit (i.e. the contents of the last commit) when
63 it happens. In other words, `git-diff --cached HEAD` must
64 report no changes.
65
66 [NOTE]
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
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
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
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
98 worry about loss of data --- you simply were not ready to do
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
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.
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
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
131 can inspect the stages with `git-ls-files -u`). The working
132 tree files have the result of "merge" program; i.e. 3-way
133 merge result with familiar conflict markers `<<< === >>>`.
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
147 * Resolve the conflicts. `git-diff` would report only the
148 conflicting paths because of the above 2. and 3.. Edit the
149 working tree files into a desirable shape, `git-add` or `git-rm`
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
154 SEE ALSO
155 --------
156 linkgit:git-fmt-merge-msg[1], linkgit:git-pull[1],
157 linkgit:gitattributes[5]
158
159
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 ---
171 Part of the linkgit:git[7] suite