From: Junio C Hamano <gitster@pobox.com>
Date: Wed, 03 Oct 2012 18:26:55 GMT
Subject: Re: push.default documented in "man git-push"?
Message-ID: <7v7gr75s40.fsf@alter.siamese.dyndns.org>
In-Reply-To: <CACsJy8APN-CdBZgLzuNWAa5ArR2gkcStY4GZ=79fU7sGT9pOMw@mail.gmail.com>

Nguyen Thai Ngoc Duy <pclouds@gmail.com> writes:

> On Wed, Oct 3, 2012 at 3:46 PM, Ramkumar Ramachandra <artagnon@gmail.com> wrote:
>> On second thought, it might not be such a good idea.  There are *lots*
>> of variables that control the operation of each command, and it's hard
>> to decide which ones to list and which ones to omit.  I've listed all
>> the relevant variables for git-push, except the advice.* variables- I
>> don't know how useful such a long list might be.
>
> I think listing receive.* and advice.* (and maybe even
> remove.<name>.*) is still ok. The goal is to give users a clue.
> They'll need to look up in config.txt anyway for explanation. If we
> name the config keys (and groups) well then users should be able to
> guess what those keys may be for before deciding whether to look into
> details.

Please do not label the list as "These variables affect this
command" to give a false impression that it is the complete list if
it isn't.

Unless somebody promises to keep an up-to-date complete list there
(or even better, come up with a mechanism to help us keep that
promise automatically, perhaps by annotating pieces with structured
comments in config.txt and automatically appending such a section to
manual pages of relevant commands), that is.

With a weaker phrase, e.g. "These configuration variables may be of
interest", such a list may not hurt readers, but personally I do not
think it adds much value to have a list of variables without even a
single line description of what each is used for.