[PATCH 0/3] Documentation: rebase and workflows

[Thomas Rast <trast@student.ethz.ch>]

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 <trast@student.ethz.ch> writes:
> > +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