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

["Ævar Arnfjörð Bjarmason" <avarab@gmail.com>]

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:

> +EXAMPLES
> +--------
> +
> +`git reflog`::
> +	Lists entries of reflog of HEAD, starting at `HEAD@{0}`.
> +
> +`git reflog HEAD`::
> +	The same.
> +
> +`git reflog show HEAD`::
> +	The same.
> +
> +`git reflog HEAD@{4}`::
> +	The same, starting at the 4th prior value of HEAD.
> +
> +`git reflog master`::
> +	Lists entries of reflog of `master`.
> +
> +`git reflog master@{0}`::
> +	The same.
> +
> +`git reflog master@{now}`::
> +	The same, show with timestamp.
> +
> +`git reflog master@{4.minutes}`::
> +	The same, starting at master, 4 minutes ago.
> +
> +For the branch that is currently checked out, you can omit the name
> +when you use any of the @{..} notation, so
> +
> +`git reflog @{0}`
> +
> +`git reflog @{now}`
> +
> +are often the easiest ways to view what you did on the current
> +branch

Most of this really just seems to be duplicating "SPECIFYING REVISIONS",
and some of it such as "show with timestamp" is ambiguous/misleading. If
I didn't know how it worked I'd think that it might affect the output
itself (maybe showing times "relative to now"), but it's just
gitrevisions syntax.

> +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.

The "SEE ALSO" section is really more for stuff like (in this case)
'git-fsck', 'git-filter-branch', 'git-rev-list' or 'git-stash'. All of
those commansd have some direct interaction with the 'reflog', but are
not mentioned in the main prose.