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 gitlink: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 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.
  75
  76 [NOTE]
  77 This is a bit of lie.  In certain special cases, your index are
  78 allowed to be different from the tree of `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 difference from your `HEAD` commit.  Otherwise, your index entries
  82 are allowed have differences from your `HEAD` commit that match
  83 the result of trivial merge (e.g. you received the same patch
  84 from 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.
  90
  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).
  96
  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.
 106
 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.
 112
 113 When things cleanly merge, these things happen:
 114
 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.
 120
 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.
 130
 131 When there are conflicts, these things happen:
 132
 133 1. `HEAD` stays the same.
 134
 135 2. Cleanly merged paths are updated both in the index file and
 136    in your working tree.
 137
 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 `<<< === >>>`.
 144
 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`.
 149
 150 After seeing a conflict, you can do two things:
 151
 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.
 156
 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.
 162
 163
 164 SEE ALSO
 165 --------
 166 gitlink:git-fmt-merge-msg[1], gitlink:git-pull[1]
 167
 168
 169 Author
 170 ------
 171 Written by Junio C Hamano <junkio@cox.net>
 172
 173
 174 Documentation
 175 --------------
 176 Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
 177
 178 GIT
 179 ---
 180 Part of the gitlink:git[7] suite