[PATCH 0/3] Documentation: rebase and workflows

Junio C Hamano wrote:

First of all, thanks for your excellent criticism of my patch.
(Thanks also to Marcus for spotting the typo, though I eventually
decided to remove the corresponding part again.)

I'm rerolling the entire series, with a few improvements to 3/3, and
following that with an interdiff.  1/3 is almost a complete rewrite.
(I realise that 3/3 is not really related to the first two, so we may
eventually have to split it off the series if it takes more time.)

All snipped comments have been addressed ... hopefully ;-)

In other words, draw it like this.  It is much easier to see what's
changed and what's unchanged, if the part that hasn't changed stayed
unchanged in the picture:

[...]

       o---o---o---o---o---o---o---o  master
            \                       \ 
             o---o---o---o---o       o'--o'--o'--o'--o' subsystem
                              \
                               *---*---*  topic

I had the old one in the other style to emphasise that all commits on
'topic' are "indistinguishable" w.r.t. source.  But this indeed makes
for nicer graphs.

Thomas Rast [off-list ref] writes:

quoted

+on 'subsystem'.  Luckily, 'git-rebase' knows to skip commits that are
+textually the same as commits in the upstream.  So if you say

There is no luck involved in "git rebase" knowing how to do this -- this
is by design.

Luckily for the user! :-)

But more importantly, at this point, there is a break in the flow of
thought in this section.  Step back and read what you wrote, pretending as
if you are reading the section for the first time, and notice:

[...]

Indeed, you are right.  I stole your "merge without rebase" drawing,
and added a paragraph about the reasons for a rebase.  However:

The problem is that the resulting history will keep two copies of the
morally equivalent commits from the subsystem.  You know that, and I know
that, but the purpose of the document is to explain it to people who do
not know it yet.

Maybe that's just me, but I always thought the duplication argument
was a bit weak.  I think reasons such as "resurrects changes that have
been (presumably for a reason) undone" are far scarier and more likely
to stop users from rebasing.  Eventually, I omitted it to keep the
justification paragraph shorter, but if others feel the same, maybe it
should go in.

- Thomas


Thomas Rast (3):
  Documentation: new upstream rebase recovery section in git-rebase
  Documentation: Refer to git-rebase(1) to warn against rewriting
  Documentation: add manpage about workflows

 Documentation/Makefile              |    2 +-
 Documentation/git-commit.txt        |    4 +
 Documentation/git-filter-branch.txt |    4 +-
 Documentation/git-rebase.txt        |  129 +++++++++++++-
 Documentation/git-reset.txt         |    4 +-
 Documentation/gitworkflows.txt      |  330 +++++++++++++++++++++++++++++++++++
 6 files changed, 465 insertions(+), 8 deletions(-)
 create mode 100644 Documentation/gitworkflows.txt