user-manual: use pithier example commit
[gitweb.git] / Documentation / git-rebase.txt
index c339c4525c500f29d51063a34f1c7d238b37c2e6..753b275a0f79d88ef439a4c235452bd17f81ce2e 100644 (file)
@@ -3,21 +3,30 @@ git-rebase(1)
 
 NAME
 ----
-git-rebase - Rebase local commits to a new head
+git-rebase - Forward-port local commits to the updated upstream head
 
 SYNOPSIS
 --------
-'git-rebase' [--merge] [--onto <newbase>] <upstream> [<branch>]
-
+[verse]
+'git-rebase' [-v] [--merge] [-C<n>] [--onto <newbase>] <upstream> [<branch>]
 'git-rebase' --continue | --skip | --abort
 
 DESCRIPTION
 -----------
-git-rebase replaces <branch> with a new branch of the same name.  When
-the --onto option is provided the new branch starts out with a HEAD equal
-to <newbase>, otherwise it is equal to <upstream>.  It then attempts to
-create a new commit for each commit from the original <branch> that does
-not exist in the <upstream> branch.
+If <branch> is specified, git-rebase will perform an automatic
+`git checkout <branch>` before doing anything else.  Otherwise
+it remains on the current branch.
+
+All changes made by commits in the current branch but that are not
+in <upstream> are saved to a temporary area.  This is the same set
+of commits that would be shown by `git log <upstream>..HEAD`.
+
+The current branch is reset to <upstream>, or <newbase> if the
+--onto option was supplied.  This has the exact same effect as
+`git reset --hard <upstream>` (or <newbase>).
+
+The commits that were previously saved into the temporary area are
+then reapplied to the current branch, one by one, in order.
 
 It is possible that a merge failure will prevent this process from being
 completely automatic.  You will have to resolve any such merge failure
@@ -26,9 +35,6 @@ that caused the merge failure with `git rebase --skip`.  To restore the
 original <branch> and remove the .dotest working files, use the command
 `git rebase --abort` instead.
 
-Note that if <branch> is not specified on the command line, the currently
-checked out branch is used.
-
 Assume the following history exists and the current branch is "topic":
 
 ------------
@@ -51,19 +57,89 @@ would be:
     D---E---F---G master
 ------------
 
-While, starting from the same point, the result of either of the following
-commands:
+The latter form is just a short-hand of `git checkout topic`
+followed by `git rebase master`.
 
-    git-rebase --onto master~1 master
-    git-rebase --onto master~1 master topic
+Here is how you would transplant a topic branch based on one
+branch to another, to pretend that you forked the topic branch
+from the latter branch, using `rebase --onto`.
 
-would be:
+First let's assume your 'topic' is based on branch 'next'.
+For example feature developed in 'topic' depends on some
+functionality which is found in 'next'.
 
 ------------
-              A'--B'--C' topic
-             /
-    D---E---F---G master
+    o---o---o---o---o  master
+         \
+          o---o---o---o---o  next
+                           \
+                            o---o---o  topic
+------------
+
+We would want to make 'topic' forked from branch 'master',
+for example because the functionality 'topic' branch depend on
+got merged into more stable 'master' branch, like this:
+
 ------------
+    o---o---o---o---o  master
+        |            \
+        |             o'--o'--o'  topic
+         \
+          o---o---o---o---o  next
+------------
+
+We can get this using the following command:
+
+    git-rebase --onto master next topic
+
+
+Another example of --onto option is to rebase part of a
+branch.  If we have the following situation:
+
+------------
+                            H---I---J topicB
+                           /
+                  E---F---G  topicA
+                 /
+    A---B---C---D  master
+------------
+
+then the command
+
+    git-rebase --onto master topicA topicB
+
+would result in:
+
+------------
+                 H'--I'--J'  topicB
+                /
+                | E---F---G  topicA
+                |/
+    A---B---C---D  master
+------------
+
+This is useful when topicB does not depend on topicA.
+
+A range of commits could also be removed with rebase.  If we have
+the following situation:
+
+------------
+    E---F---G---H---I---J  topicA
+------------
+
+then the command
+
+    git-rebase --onto topicA~5 topicA~2 topicA
+
+would result in the removal of commits F and G:
+
+------------
+    E---H'---I'---J'  topicA
+------------
+
+This is useful if F and G were flawed in some way, or should not be
+part of topicA.  Note that the argument to --onto and the <upstream>
+parameter can be any valid commit-ish.
 
 In case of conflict, git-rebase will stop at the first problematic commit
 and leave conflict markers in the tree.  You can use git diff to locate
@@ -72,7 +148,7 @@ file you edit, you need to tell git that the conflict has been resolved,
 typically this would be done with
 
 
-    git update-index <filename>
+    git add <filename>
 
 
 After resolving the conflict manually and updating the index with the
@@ -92,10 +168,12 @@ OPTIONS
 <newbase>::
        Starting point at which to create the new commits. If the
        --onto option is not specified, the starting point is
-       <upstream>.
+       <upstream>.  May be any valid commit, and not just an
+       existing branch name.
 
 <upstream>::
-       Upstream branch to compare against.
+       Upstream branch to compare against.  May be any valid commit,
+       not just an existing branch name.
 
 <branch>::
        Working branch; defaults to HEAD.
@@ -108,7 +186,6 @@ OPTIONS
 
 --skip::
        Restart the rebasing process by skipping the current patch.
-       This does not work with the --merge option.
 
 --merge::
        Use merging strategies to rebase.  When the recursive (default) merge
@@ -122,6 +199,15 @@ OPTIONS
        is used instead (`git-merge-recursive` when merging a single
        head, `git-merge-octopus` otherwise).  This implies --merge.
 
+-v, \--verbose::
+       Display a diffstat of what changed upstream since the last rebase.
+
+-C<n>::
+       Ensure at least <n> lines of surrounding context match before
+       and after each change.  When fewer lines of surrounding
+       context exist they all must match.  By default no context is
+       ever ignored.
+
 include::merge-strategies.txt[]
 
 NOTES