rev-list: add --branches, --tags and --remotes
[git/jnareb-git.git] / Documentation / git-merge.txt
blob0c9ad7f2bbdf4872882d127804e7c474729c0818
1 git-merge(1)
2 ============
4 NAME
5 ----
6 git-merge - Join two or more development histories together
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>...
16 DESCRIPTION
17 -----------
18 This is the top-level interface to the merge machinery
19 which drives multiple merge strategy scripts.
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>`.
26 OPTIONS
27 -------
28 include::merge-options.txt[]
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.
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.
40 include::merge-strategies.txt[]
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].
47 CONFIGURATION
48 -------------
50 merge.summary::
51         Whether to include summaries of merged commits in newly
52         created merge commit. False by default.
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.
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.
67 HOW MERGE WORKS
68 ---------------
70 A merge is always between the current `HEAD` and one or more
71 remote branch heads, and the index file must exactly match the
72 tree of `HEAD` commit (i.e. the contents of the last commit) when
73 it happens.  In other words, `git-diff --cached HEAD` must
74 report no changes.
76 [NOTE]
77 This is a bit of a lie.  In certain special cases, your index is
78 allowed to be different from the tree of the `HEAD` commit.  The most
79 notable case is when your `HEAD` commit is already ahead of what
80 is being merged, in which case your index can have arbitrary
81 differences from your `HEAD` commit.  Also, your index entries
82 may have differences from your `HEAD` commit that match
83 the result of a trivial merge (e.g. you received the same patch
84 from an external source to produce the same result as what you are
85 merging).  For example, if a path did not exist in the common
86 ancestor and your head commit but exists in the tree you are
87 merging into your repository, and if you already happen to have
88 that path exactly in your index, the merge does not have to
89 fail.
91 Otherwise, merge will refuse to do any harm to your repository
92 (that is, it may fetch the objects from remote, and it may even
93 update the local branch used to keep track of the remote branch
94 with `git pull remote rbranch:lbranch`, but your working tree,
95 `.git/HEAD` pointer and index file are left intact).
97 You may have local modifications in the working tree files.  In
98 other words, `git-diff` is allowed to report changes.
99 However, the merge uses your working tree as the working area,
100 and in order to prevent the merge operation from losing such
101 changes, it makes sure that they do not interfere with the
102 merge. Those complex tables in read-tree documentation define
103 what it means for a path to "interfere with the merge".  And if
104 your local modifications interfere with the merge, again, it
105 stops before touching anything.
107 So in the above two "failed merge" case, you do not have to
108 worry about loss of data --- you simply were not ready to do
109 a merge, so no merge happened at all.  You may want to finish
110 whatever you were in the middle of doing, and retry the same
111 pull after you are done and ready.
113 When things cleanly merge, these things happen:
115 1. The results are updated both in the index file and in your
116    working tree;
117 2. Index file is written out as a tree;
118 3. The tree gets committed; and
119 4. The `HEAD` pointer gets advanced.
121 Because of 2., we require that the original state of the index
122 file to match exactly the current `HEAD` commit; otherwise we
123 will write out your local changes already registered in your
124 index file along with the merge result, which is not good.
125 Because 1. involves only the paths different between your
126 branch and the remote branch you are pulling from during the
127 merge (which is typically a fraction of the whole tree), you can
128 have local modifications in your working tree as long as they do
129 not overlap with what the merge updates.
131 When there are conflicts, these things happen:
133 1. `HEAD` stays the same.
135 2. Cleanly merged paths are updated both in the index file and
136    in your working tree.
138 3. For conflicting paths, the index file records up to three
139    versions; stage1 stores the version from the common ancestor,
140    stage2 from `HEAD`, and stage3 from the remote branch (you
141    can inspect the stages with `git-ls-files -u`).  The working
142    tree files have the result of "merge" program; i.e. 3-way
143    merge result with familiar conflict markers `<<< === >>>`.
145 4. No other changes are done.  In particular, the local
146    modifications you had before you started merge will stay the
147    same and the index entries for them stay as they were,
148    i.e. matching `HEAD`.
150 After seeing a conflict, you can do two things:
152  * Decide not to merge.  The only clean-up you need are to reset
153    the index file to the `HEAD` commit to reverse 2. and to clean
154    up working tree changes made by 2. and 3.; `git-reset` can
155    be used for this.
157  * Resolve the conflicts.  `git-diff` would report only the
158    conflicting paths because of the above 2. and 3..  Edit the
159    working tree files into a desirable shape, `git-add` or `git-rm`
160    them, to make the index file contain what the merge result
161    should be, and run `git-commit` to commit the result.
164 SEE ALSO
165 --------
166 linkgit:git-fmt-merge-msg[1], linkgit:git-pull[1],
167 linkgit:gitattributes[5]
170 Author
171 ------
172 Written by Junio C Hamano <junkio@cox.net>
175 Documentation
176 --------------
177 Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
181 Part of the linkgit:git[7] suite