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