git-rebase: support --whitespace=<option>

[git.git] / Documentation / git-rebase.txt

diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt
index 96907d48632be36d0d8c66f6a0b4d937b7a38cb6..0858fa8a6326a0c457bc9b4bb63ae35d3001ef65 100644 (file)
--- a/Documentation/git-rebase.txt
+++ b/Documentation/git-rebase.txt
@@ -8,8 +8,9 @@ git-rebase - Forward-port local commits to the updated upstream head
 SYNOPSIS
 --------
 [verse]
-'git-rebase' [-i | --interactive] [-v | --verbose] [--merge] [-C<n>]
-       [-p | --preserve-merges] [--onto <newbase>] <upstream> [<branch>]
+'git-rebase' [-i | --interactive] [-v | --verbose] [-m | --merge]
+       [-C<n>] [ --whitespace=<option>] [-p | --preserve-merges]
+       [--onto <newbase>] <upstream> [<branch>]
 'git-rebase' --continue | --skip | --abort
 
 DESCRIPTION
@@ -130,7 +131,7 @@ the following situation:
 
 then the command
 
-    git-rebase --onto topicA~5 topicA~2 topicA
+    git-rebase --onto topicA~5 topicA~3 topicA
 
 would result in the removal of commits F and G:
 
@@ -188,7 +189,7 @@ OPTIONS
 --skip::
        Restart the rebasing process by skipping the current patch.
 
---merge::
+-m, \--merge::
        Use merging strategies to rebase.  When the recursive (default) merge
        strategy is used, this allows rebase to be aware of renames on the
        upstream side.
@@ -209,9 +210,14 @@ OPTIONS
        context exist they all must match.  By default no context is
        ever ignored.
 
+--whitespace=<nowarn|warn|error|error-all|strip>::
+       This flag is passed to the `git-apply` program
+       (see gitlink:git-apply[1]) that applies the patch.
+
 -i, \--interactive::
        Make a list of the commits which are about to be rebased.  Let the
-       user edit that list before rebasing.
+       user edit that list before rebasing.  This mode can also be used to
+       split commits (see SPLITTING COMMITS below).
 
 -p, \--preserve-merges::
        Instead of ignoring merges, try to recreate them.  This option
@@ -325,6 +331,42 @@ sure that the current HEAD is "B", and call
 $ git rebase -i -p --onto Q O
 -----------------------------
 
+
+SPLITTING COMMITS
+-----------------
+
+In interactive mode, you can mark commits with the action "edit".  However,
+this does not necessarily mean that 'git rebase' expects the result of this
+edit to be exactly one commit.  Indeed, you can undo the commit, or you can
+add other commits.  This can be used to split a commit into two:
+
+- Start an interactive rebase with 'git rebase -i <commit>^', where
+  <commit> is the commit you want to split.  In fact, any commit range
+  will do, as long as it contains that commit.
+
+- Mark the commit you want to split with the action "edit".
+
+- When it comes to editing that commit, execute 'git reset HEAD^'.  The
+  effect is that the HEAD is rewound by one, and the index follows suit.
+  However, the working tree stays the same.
+
+- Now add the changes to the index that you want to have in the first
+  commit.  You can use gitlink:git-add[1] (possibly interactively) and/or
+  gitlink:git-gui[1] to do that.
+
+- Commit the now-current index with whatever commit message is appropriate
+  now.
+
+- Repeat the last two steps until your working tree is clean.
+
+- Continue the rebase with 'git rebase --continue'.
+
+If you are not absolutely sure that the intermediate revisions are
+consistent (they compile, pass the testsuite, etc.) you should use
+gitlink:git-stash[1] to stash away the not-yet-committed changes
+after each commit, test, and amend the commit if fixes are necessary.
+
+
 Authors
 ------
 Written by Junio C Hamano <junkio@cox.net> and