Re: [PATCH 5/7] git-log.txt: generalize <since>..<until>
Ramkumar Ramachandra <artagnon@gmail.com> writes:
Show 36 quoted lines
> '<since>..<until>' is misleading, as there are many other forms that
> 'git log' can accept as an argument. Replace it with <revision range>,
> referring to the section "Specifying Ranges" in revisions.txt, and
> rewrite the section appropriately.
>
> Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>
> ---
> Documentation/git-log.txt | 16 +++++++++-------
> 1 file changed, 9 insertions(+), 7 deletions(-)
>
> diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt
> index 64cc337..c238475 100644
> --- a/Documentation/git-log.txt
> +++ b/Documentation/git-log.txt
> @@ -9,7 +9,7 @@ git-log - Show commit logs
> SYNOPSIS
> --------
> [verse]
> -'git log' [<options>] [<since>..<until>] [[\--] <path>...]
> +'git log' [<options>] [<revision range>] [[\--] <path>...]
>
> DESCRIPTION
> -----------
> @@ -62,12 +62,14 @@ produced by --stat etc.
> Note that only message is considered, if also a diff is shown
> its size is not included.
>
> -<since>..<until>::
> - Show only commits between the named two commits. When
> - either <since> or <until> is omitted, it defaults to
> - `HEAD`, i.e. the tip of the current branch.
> - For a more complete list of ways to spell <since>
> - and <until>, see linkgit:gitrevisions[7].
> +<revision range>::
> + Show only commits in the specified revision range. When no
> + <revision range> is specified, it defaults to 'HEAD' (ie. the
s/ie/i.e./; or s/ie/meaning /;
Show 5 quoted lines
> + whole history leading to the current commit). master..HEAD
> + specifies all the commits reachable from 'HEAD', but not from
> + 'master'. For a complete list of ways to spell
> + <revision range>, see the "Specifying Ranges" section of
> + linkgit:gitrevisions[7].
If you want to have a single example (other than 'HEAD' which has to be there anyway to describe the default), I think it would be more helpful to use one that would be common for not-so-advanced users, e.g. "origin..HEAD", without many other prerequisites (e.g. "@{u}.." may be common among more advanced users but is not appropriate here, because the reader may not have learned @{upstream} or omission of a side of a range defaulting to HEAD).
... `origin..HEAD` specifies all the commits reachable from
the current commit (i.e. `HEAD`) but not from `origin`.
I could squash these in locally without a reroll, but I haven't read the remainder of the series yet, so we'll see.
> [\--] <path>...::
> Show only commits that are enough to explain how the files
Ramkumar Ramachandra