Re: Advice on edits to git-rebase man page

Matthew Brett [off-list ref] writes:

Obviously my page as it is now is very different in tone from the
git-rebase page, but I think there are some aspects that could be
fruitfully merged.   Would you be interested in patches of this sort,
or does the page seem too far from the intention of the man page?

I think it is deliberate that manpages are not written as tutorial, but
as more advanced technical documentation. Just like learning Unix can
hardly be done by reading "man ls", "man cd", ... the best entry point
to learn Git is not the manpages. OTOH, I usually like Git's manpages
when I know what I'm looking for.

All that being said, there's a lot of room for improvement in our
manpages, event remaining in a technical-style. I'm not a good juge
because I already learnt how rebase works long ago, but the git rebase
man page does seem terrible for bare mortals:

  NAME
       git-rebase - Forward-port local commits to the updated upstream head

=> Quite technical already.

  DESCRIPTION
       If <branch> is specified, git rebase will perform an automatic
       git checkout <branch> before doing anything else. Otherwise it
       remains on the current branch.

=> Ouch, do we really want to start a documentation like this?

So, the DESCRIPTION part can definitely be improved IMHO. Your notation
<graft-point>, <exclude-from> and <include-from> may be an improvement
already.

Some concrete examples may help too, like "I started developing against
origin/foo, on local branch bar, and now want to rebase my work on top
of origin/boz".

My 2 cents,

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/