Re: [PATCH] git-reflog.txt: add an EXAMPLES section

[Junio C Hamano <gitster@pobox.com>]

Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:

> On Mon, Oct 03 2022, Elia Pinto wrote:
>
>> This commit adds an "EXAMPLES" section to the git reflog man page.
>> This new section currently provides examples of using git reflog
>> with branches, for which doubts often exist. In this commit we also
>> add a "SEE ALSO" section which refers to further information
>> on git commands or documentation referenced in the git reflog man page.
>
> I think it can be valuable to have an EXAMPLES section, but:
> ...
> Most of this really just seems to be duplicating "SPECIFYING REVISIONS",
> and some of it such as "show with timestamp" is ambiguous/misleading.

It would become immediately clear what these phrases want to say,
when the reader runs "git reflog @{0}" and "git reflog @{now}" while
reading the document.  I am not sure if the description is ambiguous
or misleading to those who haven't seen any reflog output, especially
the timestamped ones.  Perhaps some sample output in the documentation
would help, do you think?

    $ git reflog -2 HEAD@{now}
    ce17cbfa2b HEAD@{Mon Oct 3 09:07:30 2022 -0700}: checkout: moving...
    ce17cbfa2b HEAD@{Mon Oct 3 09:07:14 2022 -0700}: am: ssh signing...
    $ git reflog -2 HEAD@{0}
    ce17cbfa2b HEAD@{0}: checkout: moving...
    ce17cbfa2b HEAD@{1}: am: ssh signing...

I would freely admit that this is one of my least favourite part of
Git UI that allows what comes inside @{} as parameter to "git
reflog" affect both the starting point (e.g. @{2.days} omits the
activities of the past 48 hours) and the format of the output.  The
taste of the design is bad, but it is what we ended up with.

>> +SEE ALSO
>> +--------
>> +linkgit:gitrevisions[7],
>> +linkgit:git-log[1]
>
> Likewise "SEE ALSO" sections can be really valuable, but they're really
> for "now that you've read the above, maybe this is also useful". It's
> not a "SEE STUFF YOU SAW BEFORE" :)
>
> In this case we link to these in the first and third paragraphs of the
> DESCRIPTION section (respectively), since explaining the revision syntax
> etc. is really core to understanding how this command works.

I do not know about that.

Only the part of the revision syntax that refers to the tip of a ref
works as input for "git reflog".  IOW, "git reflog seen^2~4" does
not work.  I do not think the knowledge of revision syntax helps
understanding how to operate the command that much because of the
above.  I agree with you that it is dubious if it is a good idea to
list gitrevisions[7] here, but for an entirely different reason.

On the other hand, git-log[1] might not be a bad thing to refer to,
in order to learn that you can say something like

    git reflog --pretty=short --stat @{now}

Thanks for a review.