Re: Advice on edits to git-rebase man page

From: Matthieu Moy <matthieu.moy@grenoble-inp.fr>
Date: Feb 5, 2015, 10:44 UTC
Message-ID: <vpqa90s4oz2.fsf@anie.imag.fr>
In-Reply-To: <CAH6Pt5pN8nrZzW+JntU5AWS1P4vu_JmdQBM_oR4Rfnh937wFPQ@mail.gmail.com>

Matthew Brett <matthew.brett@gmail.com> 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/