Re: [PATCH 5/8] reflog: rearrange the manpage

From: Junio C Hamano <gitster@pobox.com>
Date: Feb 12, 2015, 20:09 UTC
Message-ID: <xmqqy4o2rixp.fsf@gitster.dls.corp.google.com>
In-Reply-To: <54DCC40E.4040506@alum.mit.edu>

Michael Haggerty <mhagger@alum.mit.edu> writes:

Show 23 quoted lines

> On 02/11/2015 12:42 AM, Stefan Beller wrote:
>> On Mon, Feb 9, 2015 at 1:12 AM, Michael Haggerty <mhagger@alum.mit.edu> wrote:
>>> ---all::
>>> -       Instead of listing <refs> explicitly, prune all refs.
>>> +--stale-fix::
>>> +       This revamps the logic -- the definition of "broken commit"
>>> +       becomes: a commit that is not reachable from any of the refs and
>>> +       there is a missing object among the commit, tree, or blob
>>> +       objects reachable from it that is not reachable from any of the
>>> +       refs.
>> 
>> --stale-fix becomes more and more irrelevant over time,
>> so why not put in at the very end even after --all ?
>> 
>> Thinking out loud:
>> (--expire=,--expire-unreachable= and --stale-fix) look like a group
>> and (--updateref --rewrite --verbose and --all) also feel like a group,
>> so you wanted to keep --stale-fix after --expire-unreachable= ?
>
> Yes, that's what I was thinking.
>
> But you are right that the docs could be improved even more, so in the
> re-roll I will make some further changes.

The subcommands of "git reflog" live in their own world. The options that are applicable to "git reflog expire" do not have much to do with what you can give to "git reflog show".

So perhaps a good first step would be to split OPTIONS section into three (or four---if we have options common to all of them), and list them under separate headings (i.e. "options applicable to all subcommands" (optional), "options for 'expire'", etc.)

Thanks.