git@vger.kernel.org list mirror (unofficial, one of many)
 help / color / mirror / Atom feed
From: Junio C Hamano <gitster@pobox.com>
To: Daniel Koning <dk@danielkoning.com>
Cc: git@vger.kernel.org
Subject: Re: [PATCH] blame: document actual range specifier behavior
Date: Thu, 08 Aug 2019 10:19:24 -0700
Message-ID: <xmqqsgqbfucj.fsf@gitster-ct.c.googlers.com> (raw)
In-Reply-To: <m2ftmcijgk.fsf@danielkoning.com> (Daniel Koning's message of "Wed, 07 Aug 2019 19:10:20 -0500")

Daniel Koning <dk@danielkoning.com> writes:

> The git-blame(1) man page says that the .. range specifier can be used
> to exclude changes "older than" a certain revision.

Thanks for spoting a loose-and-colloquial use of "older than" in the
doc.  As you suspect, the document wanted the phrase to be understood
as "reachable from" (a.k.a "ancestor of").  

Before reading your proposed updated text, I feared that an attempt
to be techinically more precise by rewriting description that uses
more colloquial "older than" may make the result cumbersome to read,
and as I suspected the result did become so, but it does not look
too bad, either, but the explanation of how boundary commits are
shown is completely lost, which is not quite satisfactory.

I personally find "unlike ... does not perform date-based cutoff" a
bit too redundant---as you know, it is known that everywhere in Git,
dots notation is about limiting by revision range a.k.a ancestry
relationships, and the reader can interpret "older than" as
"reachable from", once the context is clear enough.  If anything,
perhaps such a description should go to "git help revisions", as it
is not just "blame" but "log". "The dots notation is not about
date-based cutoff, unlike the --since/--until options" is shared by
all history traversal tools.

>  which limits the annotation to the body of the `hello` subroutine.
>
> -When you are not interested in changes older than version
> -v2.6.18, or changes older than 3 weeks, you can use revision
> -range specifiers  similar to 'git rev-list':
> -
> -	git blame v2.6.18.. -- foo
> -	git blame --since=3.weeks -- foo
> -
> -When revision range specifiers are used to limit the annotation,
> -lines that have not changed since the range boundary (either the
> -commit v2.6.18 or the most recent commit that is more than 3
> -weeks old in the above example) are blamed for that range
> -boundary commit.
> +When you are only interested in recent changes, you can use revision
> +range specifiers and limiting options, just as with 'git rev-list'.
> +
> +You can limit the annotation to commits from the past 3 weeks:
> +
> +  git blame --since=3.weeks -- foo
> +
> +The oldest commit in that span of time will be given the blame for any
> +lines that have not changed since.
> +
> +Or you can limit the annotation to commits that are not ancestors of
> +v2.6.18:
> +
> +  git blame v2.6.18.. -- foo
> +
> +Unlike the --since option, the two-dot range specifier does not perform
> +a date-based cutoff. If changes from branch `fix` were merged in after
> +v2.6.18, the commits on `fix` which introduced those changes will appear
> +in the output of 'git blame', even if those commits took place at an
> +earlier time than v2.6.18.
>
>  A particularly useful way is to see if an added file has lines
>  created by copy-and-paste from existing files.  Sometimes this
> --
> 2.20.1

  reply	other threads:[~2019-08-08 17:19 UTC|newest]

Thread overview: 3+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2019-08-08  0:10 Daniel Koning
2019-08-08 17:19 ` Junio C Hamano [this message]
2019-08-09 16:58   ` Junio C Hamano

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: http://vger.kernel.org/majordomo-info.html

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=xmqqsgqbfucj.fsf@gitster-ct.c.googlers.com \
    --to=gitster@pobox.com \
    --cc=dk@danielkoning.com \
    --cc=git@vger.kernel.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

git@vger.kernel.org list mirror (unofficial, one of many)

This inbox may be cloned and mirrored by anyone:

	git clone --mirror https://public-inbox.org/git
	git clone --mirror http://ou63pmih66umazou.onion/git
	git clone --mirror http://czquwvybam4bgbro.onion/git
	git clone --mirror http://hjrcffqmbrq6wope.onion/git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V1 git git/ https://public-inbox.org/git \
		git@vger.kernel.org
	public-inbox-index git

Example config snippet for mirrors.
Newsgroups are available over NNTP:
	nntp://news.public-inbox.org/inbox.comp.version-control.git
	nntp://ou63pmih66umazou.onion/inbox.comp.version-control.git
	nntp://czquwvybam4bgbro.onion/inbox.comp.version-control.git
	nntp://hjrcffqmbrq6wope.onion/inbox.comp.version-control.git
	nntp://news.gmane.io/gmane.comp.version-control.git
 note: .onion URLs require Tor: https://www.torproject.org/

code repositories for the project(s) associated with this inbox:

	https://80x24.org/mirrors/git.git

AGPL code for this site: git clone https://public-inbox.org/public-inbox.git