[PATCH 0/3] Documentation: rebase and workflows
- From
Thomas Rast <trast@student.ethz.ch>
- Date
- Sep 13, 2008, 16:10 UTC
- Message-ID
- <1221322263-25291-1-git-send-email-trast@student.ethz.ch>
- In-Reply-To
- <7v8wtwk4yp.fsf@gitster.siamese.dyndns.org>
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:
[...]
Show 5 quoted lines
> 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.
Show 6 quoted lines
> 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