Re: [PATCH] Add commands that git-gc runs underneath

From: David Kastrup <dak@gnu.org>
Date: Aug 31, 2007, 19:25 UTC
Message-ID: <85wsvbbj6c.fsf@lola.goethe.zz>
In-Reply-To: <46D7E058.9050001@op5.se>

Andreas Ericsson <ae@op5.se> writes:

Show 22 quoted lines

> Junio C Hamano wrote:
>> Andreas Ericsson <ae@op5.se> writes:
>>
>>> When gc was a shell-script, it was fairly easy to find out the command-
>>> sequence...
>>
>> Maybe referring more advanced/curious users to contrib/examples/
>> directory is a good idea, but not necessarily from manpages of
>> the commands that have been rewritten in C.
>>
>> I think contrib/examples/ needs a README file that effectively
>> say "these are the last versions of shell script implementation
>> of the commands before they were rewritten in C.  New features
>> may have been added to the built-in ones but these example
>> scripts are not kept up to date.  They are here to serve as
>> examples to show you how you would pipeline the plumbing level
>> commands."
>>
>
> Sensible, and also avoids the possible bitrot problem with the
> man-page should there be additional actions added to standard
> git-gc operations.

Let's just make all manual pages empty, and then we have solved all manual page bitrot problems in one fell swoop.

Really: I don't see how this helps at all.  If I am interested in
seeing what operations git-gc performs, I am not interested in some
historical script's behavior.

Hiding that information into contrib/examples and telling people that it may be wrong, anyway, is not really helpful as a way of documenting git-gc's behavior.

Of _course_, _any_ useful documentation will have a "possible bitrot problem with the man-page" whenever code is changed. The solution is not to make the manual pages as useless as possible so that nothing can be subject to bitrot. The solution is to update the information.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum