Re: Notes and questions while reading the documentation

From: Junio C Hamano <junkio@cox.net>
Date: Oct 5, 2005, 23:30 UTC
Message-ID: <7v1x2zfsp2.fsf@assigned-by-dhcp.cox.net>
In-Reply-To: <1128549966.11363.29.camel@localhost>

Christian Meder <chris@absolutegiganten.org> writes:

Show 5 quoted lines

> * a lot of the manpages include something like "v0.1, June 2005" in the
> header; these versions tags are pretty obscure to interpret, timestamp
> when last edited ? version of the manpage ? version of git when the
> manpage was included ? maturity the author assigned to the content ?
> If these tags don't follow some sane schema they should be removed.

I think the original intent was the last modification datestamp and the version of the documentation, but I agree it should be removed. I do not think they show on the HTML version, nor man pages, although I have to admit that I haven't looked at generated manpages for some time.

> * git-applymbox: -q for interactivity seems like a strange choice, ok I
> knew -i for interactive and -q for quiet but -q for interactive editing
> is _not_ really intuitive

Last night I felt the same way, and an rewrite [*1*] of applymbox I am working on uses '-i' instead. If users do not object, I would vote for changing applymbox to use '-i' as well.

The user community consensus does not have to be unanimous, but anybody who has linux kernel tree on kernel.org servers has a veto on this, I should say. It's the tool they use every day.

> * the usage of git, Git and GIT isn't consistent in the documentation.
> I'd vote for only using git.

Sounds sane.  What would we do if we need to start sentences with it?

> * git-clone says that http transport is not supported yet I used it to
> clone the git repo from kernel.org yesterday. Should the documentation
> get updated ?

Thanks for noticing. Yes, now HTTP can handle both of the trickier setups (packed, and alternates); credit goes to Daniel.

> * the manpage synopsises aren't consistent wrt command naming; it's "git
> commit" but "git-branch"; I guess all the manpages should reference
> their commands as "git-x" and not "git x"

Agreed.

Again, thanks for taking the time to do this.

[Footnote]

*1* Why rewrite? One reason was I was afraid to break things for Linus ;-). And I wanted to add a bit more interactivity and restartability. The ultimate goal is to make 'git-rebase' and 'git-cherry-pick' faster and easier to use. The idea is not to always do 3-way merge, but essentailly feed format-patch output (now it can do --stdout) into the new applymbox, and when patch applies cleanly things will go faster, otherwise it will fall back to 3-way merge behaviour.