| Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 1 | git-merge(1) |
| 2 | ============ |
| 3 | |
| 4 | NAME |
| 5 | ---- |
| Junio C Hamano | 7c73c66 | 2007-01-19 00:37:50 | [diff] [blame^] | 6 | git-merge - Join two or more development histories together |
| Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 7 | |
| 8 | |
| 9 | SYNOPSIS |
| 10 | -------- |
| Junio C Hamano | ee6d961 | 2006-11-27 20:03:22 | [diff] [blame] | 11 | [verse] |
| 12 | 'git-merge' [-n] [--no-commit] [--squash] [-s <strategy>]... |
| Junio C Hamano | ee6d961 | 2006-11-27 20:03:22 | [diff] [blame] | 13 | -m=<msg> <remote> <remote>... |
| Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 14 | |
| 15 | DESCRIPTION |
| 16 | ----------- |
| Junio C Hamano | ee6d961 | 2006-11-27 20:03:22 | [diff] [blame] | 17 | This is the top-level interface to the merge machinery |
| Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 18 | which drives multiple merge strategy scripts. |
| 19 | |
| 20 | |
| 21 | OPTIONS |
| 22 | ------- |
| 23 | include::merge-options.txt[] |
| 24 | |
| 25 | <msg>:: |
| 26 | The commit message to be used for the merge commit (in case |
| 27 | it is created). The `git-fmt-merge-msg` script can be used |
| 28 | to give a good default for automated `git-merge` invocations. |
| 29 | |
| 30 | <head>:: |
| Junio C Hamano | ee6d961 | 2006-11-27 20:03:22 | [diff] [blame] | 31 | Our branch head commit. This has to be `HEAD`, so new |
| 32 | syntax does not require it |
| Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 33 | |
| 34 | <remote>:: |
| Junio C Hamano | ee6d961 | 2006-11-27 20:03:22 | [diff] [blame] | 35 | Other branch head merged into our branch. You need at |
| Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 36 | least one <remote>. Specifying more than one <remote> |
| 37 | obviously means you are trying an Octopus. |
| 38 | |
| 39 | include::merge-strategies.txt[] |
| 40 | |
| 41 | |
| 42 | If you tried a merge which resulted in a complex conflicts and |
| 43 | would want to start over, you can recover with |
| 44 | gitlink:git-reset[1]. |
| 45 | |
| 46 | |
| 47 | HOW MERGE WORKS |
| 48 | --------------- |
| 49 | |
| 50 | A merge is always between the current `HEAD` and one or more |
| 51 | remote branch heads, and the index file must exactly match the |
| 52 | tree of `HEAD` commit (i.e. the contents of the last commit) when |
| 53 | it happens. In other words, `git-diff --cached HEAD` must |
| 54 | report no changes. |
| 55 | |
| 56 | [NOTE] |
| 57 | This is a bit of lie. In certain special cases, your index are |
| 58 | allowed to be different from the tree of `HEAD` commit. The most |
| 59 | notable case is when your `HEAD` commit is already ahead of what |
| 60 | is being merged, in which case your index can have arbitrary |
| 61 | difference from your `HEAD` commit. Otherwise, your index entries |
| 62 | are allowed have differences from your `HEAD` commit that match |
| 63 | the result of trivial merge (e.g. you received the same patch |
| 64 | from external source to produce the same result as what you are |
| 65 | merging). For example, if a path did not exist in the common |
| 66 | ancestor and your head commit but exists in the tree you are |
| 67 | merging into your repository, and if you already happen to have |
| 68 | that path exactly in your index, the merge does not have to |
| 69 | fail. |
| 70 | |
| 71 | Otherwise, merge will refuse to do any harm to your repository |
| 72 | (that is, it may fetch the objects from remote, and it may even |
| 73 | update the local branch used to keep track of the remote branch |
| 74 | with `git pull remote rbranch:lbranch`, but your working tree, |
| 75 | `.git/HEAD` pointer and index file are left intact). |
| 76 | |
| 77 | You may have local modifications in the working tree files. In |
| 78 | other words, `git-diff` is allowed to report changes. |
| 79 | However, the merge uses your working tree as the working area, |
| 80 | and in order to prevent the merge operation from losing such |
| 81 | changes, it makes sure that they do not interfere with the |
| 82 | merge. Those complex tables in read-tree documentation define |
| 83 | what it means for a path to "interfere with the merge". And if |
| 84 | your local modifications interfere with the merge, again, it |
| 85 | stops before touching anything. |
| 86 | |
| 87 | So in the above two "failed merge" case, you do not have to |
| Junio C Hamano | 51c2ab0 | 2006-07-09 20:38:54 | [diff] [blame] | 88 | worry about loss of data --- you simply were not ready to do |
| Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 89 | a merge, so no merge happened at all. You may want to finish |
| 90 | whatever you were in the middle of doing, and retry the same |
| 91 | pull after you are done and ready. |
| 92 | |
| 93 | When things cleanly merge, these things happen: |
| 94 | |
| 95 | 1. the results are updated both in the index file and in your |
| 96 | working tree, |
| 97 | 2. index file is written out as a tree, |
| 98 | 3. the tree gets committed, and |
| 99 | 4. the `HEAD` pointer gets advanced. |
| 100 | |
| 101 | Because of 2., we require that the original state of the index |
| 102 | file to match exactly the current `HEAD` commit; otherwise we |
| 103 | will write out your local changes already registered in your |
| 104 | index file along with the merge result, which is not good. |
| 105 | Because 1. involves only the paths different between your |
| 106 | branch and the remote branch you are pulling from during the |
| 107 | merge (which is typically a fraction of the whole tree), you can |
| 108 | have local modifications in your working tree as long as they do |
| 109 | not overlap with what the merge updates. |
| 110 | |
| 111 | When there are conflicts, these things happen: |
| 112 | |
| 113 | 1. `HEAD` stays the same. |
| 114 | |
| 115 | 2. Cleanly merged paths are updated both in the index file and |
| 116 | in your working tree. |
| 117 | |
| 118 | 3. For conflicting paths, the index file records up to three |
| 119 | versions; stage1 stores the version from the common ancestor, |
| 120 | stage2 from `HEAD`, and stage3 from the remote branch (you |
| 121 | can inspect the stages with `git-ls-files -u`). The working |
| 122 | tree files have the result of "merge" program; i.e. 3-way |
| 123 | merge result with familiar conflict markers `<<< === >>>`. |
| 124 | |
| 125 | 4. No other changes are done. In particular, the local |
| 126 | modifications you had before you started merge will stay the |
| 127 | same and the index entries for them stay as they were, |
| 128 | i.e. matching `HEAD`. |
| 129 | |
| 130 | After seeing a conflict, you can do two things: |
| 131 | |
| 132 | * Decide not to merge. The only clean-up you need are to reset |
| 133 | the index file to the `HEAD` commit to reverse 2. and to clean |
| 134 | up working tree changes made by 2. and 3.; `git-reset` can |
| 135 | be used for this. |
| 136 | |
| 137 | * Resolve the conflicts. `git-diff` would report only the |
| 138 | conflicting paths because of the above 2. and 3.. Edit the |
| 139 | working tree files into a desirable shape, `git-update-index` |
| 140 | them, to make the index file contain what the merge result |
| 141 | should be, and run `git-commit` to commit the result. |
| 142 | |
| 143 | |
| 144 | SEE ALSO |
| 145 | -------- |
| 146 | gitlink:git-fmt-merge-msg[1], gitlink:git-pull[1] |
| 147 | |
| 148 | |
| 149 | Author |
| 150 | ------ |
| 151 | Written by Junio C Hamano <junkio@cox.net> |
| 152 | |
| 153 | |
| 154 | Documentation |
| 155 | -------------- |
| 156 | Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. |
| 157 | |
| 158 | GIT |
| 159 | --- |
| 160 | Part of the gitlink:git[7] suite |
