[PATCH] git-rebase: document suppression of duplicate commits

[PATCH] git-rebase: document suppression of duplicate commits

[Jeff King]

git-rebase uses format-patch's --ignore-if-in-upstream
option, but we never document the user-visible behavior. The
example is placed near the top of the example list rather
than at the bottom because it is:
  a. a simple example
  b. a reasonably common scenario for many projects (mail
     some patches which get accepted upstream, then rebase)

Signed-off-by: Jeff King <peff@peff.net>
---
On Sat, Oct 13, 2007 at 07:04:52PM -0400, Michael Witten wrote:
> I can make a patch, but at the moment I'm swamped and I don't want to
> think about doing that.

And whoever said procrastination didn't get things done?

 Documentation/git-rebase.txt |   25 ++++++++++++++++++++++++-
 1 files changed, 24 insertions(+), 1 deletions(-)

diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt
index e8e7579..b6efb48 100644
--- a/Documentation/git-rebase.txt
+++ b/Documentation/git-rebase.txt
@@ -28,7 +28,10 @@ The current branch is reset to <upstream>, or <newbase> if the
 `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.
+then reapplied to the current branch, one by one, in order. Note that
+any commits in HEAD which introduce the same textual changes as a commit
+in <upstream>..HEAD are omitted (i.e., a patch already accepted upstream
+with a different commit message or timestamp will be skipped).
 
 It is possible that a merge failure will prevent this process from being
 completely automatic.  You will have to resolve any such merge failure
@@ -62,6 +65,26 @@ would be:
 The latter form is just a short-hand of `git checkout topic`
 followed by `git rebase master`.
 
+If the upstream branch already contains a change you have made (e.g.,
+because you mailed a patch which was applied upstream), then that commit
+will be skipped. For example, running `git-rebase master` on the
+following history (in which A' and A introduce the same set of changes,
+but have different committer information):
+
+------------
+          A---B---C topic
+         /
+    D---E---A'---F master
+------------
+
+will result in:
+
+------------
+                   B'---C' topic
+                  /
+    D---E---A'---F master
+------------
+
 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`.
-- 
1.5.3.4.1155.gfe96ee-dirty

Re: [PATCH] git-rebase: document suppression of duplicate commits

[Michael Witten]

On 15 Oct 2007, at 12:47:30 AM, Jeff King wrote:

> On Sat, Oct 13, 2007 at 07:04:52PM -0400, Michael Witten wrote:
>> I can make a patch, but at the moment I'm swamped and I don't want to
>> think about doing that.
>
> And whoever said procrastination didn't get things done?

:-)

Thanks.

I'm pretty bad at setting priories, so I apologize for
saying I'm swamped and then turning around to submit
other patches.

Sincerely,
Michael Witten