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).  In addition,
  85 merge always sets `.git/ORIG_HEAD` to the original state of HEAD so
  86 a problematic merge can be removed by using `git reset ORIG_HEAD`.
  87
  88 You may have local modifications in the working tree files.  In
  89 other words, 'git-diff' is allowed to report changes.
  90 However, the merge uses your working tree as the working area,
  91 and in order to prevent the merge operation from losing such
  92 changes, it makes sure that they do not interfere with the
  93 merge. Those complex tables in read-tree documentation define
  94 what it means for a path to "interfere with the merge".  And if
  95 your local modifications interfere with the merge, again, it
  96 stops before touching anything.
  97
  98 So in the above two "failed merge" case, you do not have to
  99 worry about loss of data --- you simply were not ready to do
 100 a merge, so no merge happened at all.  You may want to finish
 101 whatever you were in the middle of doing, and retry the same
 102 pull after you are done and ready.
 103
 104 When things cleanly merge, these things happen:
 105
 106 1. The results are updated both in the index file and in your
 107    working tree;
 108 2. Index file is written out as a tree;
 109 3. The tree gets committed; and
 110 4. The `HEAD` pointer gets advanced.
 111
 112 Because of 2., we require that the original state of the index
 113 file to match exactly the current `HEAD` commit; otherwise we
 114 will write out your local changes already registered in your
 115 index file along with the merge result, which is not good.
 116 Because 1. involves only the paths different between your
 117 branch and the remote branch you are pulling from during the
 118 merge (which is typically a fraction of the whole tree), you can
 119 have local modifications in your working tree as long as they do
 120 not overlap with what the merge updates.
 121
 122 When there are conflicts, these things happen:
 123
 124 1. `HEAD` stays the same.
 125
 126 2. Cleanly merged paths are updated both in the index file and
 127    in your working tree.
 128
 129 3. For conflicting paths, the index file records up to three
 130    versions; stage1 stores the version from the common ancestor,
 131    stage2 from `HEAD`, and stage3 from the remote branch (you
 132    can inspect the stages with `git ls-files -u`).  The working
 133    tree files have the result of "merge" program; i.e. 3-way
 134    merge result with familiar conflict markers `<<< === >>>`.
 135
 136 4. No other changes are done.  In particular, the local
 137    modifications you had before you started merge will stay the
 138    same and the index entries for them stay as they were,
 139    i.e. matching `HEAD`.
 140
 141 After seeing a conflict, you can do two things:
 142
 143  * Decide not to merge.  The only clean-up you need are to reset
 144    the index file to the `HEAD` commit to reverse 2. and to clean
 145    up working tree changes made by 2. and 3.; 'git-reset' can
 146    be used for this.
 147
 148  * Resolve the conflicts.  `git diff` would report only the
 149    conflicting paths because of the above 2. and 3.  Edit the
 150    working tree files into a desirable shape, 'git-add' or 'git-rm'
 151    them, to make the index file contain what the merge result
 152    should be, and run 'git-commit' to commit the result.
 153
 154
 155 SEE ALSO
 156 --------
 157 linkgit:git-fmt-merge-msg[1], linkgit:git-pull[1],
 158 linkgit:gitattributes[5],
 159 linkgit:git-reset[1],
 160 linkgit:git-diff[1], linkgit:git-ls-files[1],
 161 linkgit:git-add[1], linkgit:git-rm[1],
 162 linkgit:git-mergetool[1]
 163
 164 Author
 165 ------
 166 Written by Junio C Hamano <junkio@cox.net>
 167
 168
 169 Documentation
 170 --------------
 171 Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
 172
 173 GIT
 174 ---
 175 Part of the linkgit:git[1] suite