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