Re: ghost refs

From: Junio C Hamano <gitster@pobox.com>
Date: Apr 8, 2010, 20:42 UTC
Message-ID: <7vbpdt65ie.fsf@alter.siamese.dyndns.org>
In-Reply-To: <20100408194908.GB4222@sigill.intra.peff.net>

Jeff King <peff@peff.net> writes:

Show 26 quoted lines

> Maybe:
>
> -- >8 --
> Subject: [PATCH] docs: clarify "branch -l"
>
> This option is mostly useless these days because we turn on
> reflogs by default in non-bare repos.
>
> Signed-off-by: Jeff King <peff@peff.net>
> ---
>  Documentation/git-branch.txt |    2 ++
>  1 files changed, 2 insertions(+), 0 deletions(-)
>
> diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
> index 903a690..d78f4c7 100644
> --- a/Documentation/git-branch.txt
> +++ b/Documentation/git-branch.txt
> @@ -72,6 +72,8 @@ OPTIONS
>  	Create the branch's reflog.  This activates recording of
>  	all changes made to the branch ref, enabling use of date
>  	based sha1 expressions such as "<branchname>@\{yesterday}".
> +	Note that in non-bare repositories, reflogs are usually
> +	enabled by default by the `core.logallrefupdates` config option.
>  
>  -f::
>  --force::

That certainly is an improvement, but I've been wondering if it makes sense to also have a section in each commands the configuration variables that affects the behaviour of the command. core.logallrefupdates surely is not the only variable that affects how "git branch" behaves.

We might want to have a general concensus on what we want to have in the documentation. As you noted, some have too sparse SYNOPSIS, while others have full list of options. Some mention configuration variables, while others don't. Some have extensive examples, while others lack any. Once we know the general direction in which we are going, we can hand off the actual documentation updates to the crowd ;-)

I'll list my preference off the top of my head as a firestarter.

NAME::

The name followed by what it is used for

SYNOPSIS::

I prefer to have (almost) complete set of options in SYNOPSIS, rather than "command [<options>] <args>..." which is next to useless. This is especially true for commands whose one set of options is incompatible with other set of options and arguments (e.g. there is no place for "-b" to "checkout" that checks out paths out of the index or a tree-ish).

I also prefer not to list "purely for backward compatibility" options in SYNOPSIS section.

DESCRIPTION::

The description section should first state what the command is used for, iow, in which situation the user might want to use that command.

OPTIONS::

List of full options. Some existing pages list them alphabetically, while others list them in functional groups. I prefer the latter which tends to make the page more concise, and is more suited for people who got used to the system (and remember, nobody stays to be a newbie forever, and people who stay to be newbies forever are not our primary audience).

Detailed discussion of concepts::

Some manual pages need to have discussion of basic concepts that would not be a good fit for the DESCRIPTION section (e.g. "Detached HEAD" section in "checkout" manual). I am not sure if this kind of material is better given in OPTIONS section close to the functional group (e.g. "History Siimplification" heading in "log" manual).

EXAMPLES::

I prefer to make it mandatory for Porcelain command manual pages to have a list of often used patterns that a reasonably intelligent person can guess how to tweak to match the particular situation s/he is in.

AUTHOR/DOCUMENTAITON::

These sections in most pages are not kept up to date, and I prefer to remove them altogether. They do not help end users who never clone git.git, and those who clone git.git will have shortlog to give them more accurate information.