rebase docs: clarify --merge and --strategy
Add a paragraph about the swapped sides in a --merge rebase, which was otherwise only documented in the sources. Add a paragraph about the effects of the 'ours' strategy to the -s description. Also remove the mention of the 'octopus' strategy, which was copied from the git-merge description but is pointless in a rebase. Signed-off-by: Thomas Rast <trast@student.ethz.ch> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Thomas Rast committed
Nov 15, 2009 at 19:25 UTC
31ddd1ee0fdd0a03001994d362023a04d8231eb0
1 file changed
+13
-3
Documentation/git-rebase.txt
+13
-3
@@ -228,13 +228,23 @@ OPTIONS
228
Use merging strategies to rebase. When the recursive (default) merge
229
strategy is used, this allows rebase to be aware of renames on the
230
upstream side.
231
++
232
+Note that a rebase merge works by replaying each commit from the working
233
+branch on top of the <upstream> branch. Because of this, when a merge
234
+conflict happens, the side reported as 'ours' is the so-far rebased
235
+series, starting with <upstream>, and 'theirs' is the working branch. In
236
+other words, the sides are swapped.
237
238
-s <strategy>::
239
--strategy=<strategy>::
240
Use the given merge strategy.
235
- If there is no `-s` option, a built-in list of strategies
236
- is used instead ('git-merge-recursive' when merging a single
237
- head, 'git-merge-octopus' otherwise). This implies --merge.
241
+ If there is no `-s` option 'git-merge-recursive' is used
242
+ instead. This implies --merge.
243
++
244
+Because 'git-rebase' replays each commit from the working branch
245
+on top of the <upstream> branch using the given strategy, using
246
+the 'ours' strategy simply discards all patches from the <branch>,
247
+which makes little sense.
248
249
-q::
250
--quiet::