From: "Ævar Arnfjörð Bjarmason" <avarab@gmail.com>
To: Jeff King <peff@peff.net>
Cc: Jonathan Nieder <jrnieder@gmail.com>,
git@vger.kernel.org, Han-Wen Nienhuys <hanwen@google.com>,
Johannes Schindelin <johannes.schindelin@gmx.de>
Subject: Re: Referring to commits in commit messages
Date: Wed, 19 Dec 2018 19:52:01 +0100 [thread overview]
Message-ID: <875zvpfiy6.fsf@evledraar.gmail.com> (raw)
In-Reply-To: <20181219182216.GA17309@sigill.intra.peff.net>
On Wed, Dec 19 2018, Jeff King wrote:
> On Wed, Dec 19, 2018 at 03:02:14PM +0100, Ævar Arnfjörð Bjarmason wrote:
>
>> On Mon, Dec 17 2018, Jonathan Nieder wrote:
>>
>> > v2.11.0-rc3~3^2~1 (stripspace: respect repository config, 2016-11-21)
>>
>> Minor nit not just on this patch, but your patches in general: I think
>> you're the only one using this type of template instead of the `%h
>> ("%s", %ad)` format documented in SubmittingPatches.
>>
>> I've had at least a couple of cases where I've git log --grep=<abbr sha>
>> and missed a commit of yours when you referred to another commit.
>>
>> E.g. when composing
>> https://public-inbox.org/git/878t0lfwrj.fsf@evledraar.gmail.com/ I
>> remembered PERLLIB_EXTRA went back & forth between
>> working/breaking/working with your/my/your patch, so:
>>
>> git log --grep=0386dd37b1
>>
>> Just found the chain up to my breaking change, but not your 7a7bfc7adc,
>> which refers to that commit as v1.9-rc0~88^2.
>>
>> Maybe this is really a feature request. I.e. maybe we should have some
>> mode where --grep=<commitish> will be combined with some mode where we
>> try to find various forms of <commitish> in commit messages, then
>> normalize & match them....
>
> That would help when you're using --grep, but not other things that are
> trying to parse the commit message. Two instances I've noticed:
>
> - web interfaces like GitHub won't linkify this type of reference
> (whereas they will for something that looks like a hex object id)
I wonder if we had some canonical plumbing combination of to `git
cat-file -p` and/or a utility like git-interpret-trailers that would
take a commit message and spew out BEGIN/END/SHA-1 positions for
commitish that we found whether sites like GitHub would use it.
They'd still need to do a second pass to for any of their own markup,
e.g. the elsewhere@<commitish> syntax, or referring to PRs/MRs issues
etc....
> - my terminal makes it easy to select hex strings, but doesn't
> understand this git-describe output :)
>
> These tools _could_ be taught a regex like /v(\d+.)(-rc\d+)?([~^]+d)*/.
> But matching hex strings is a lot simpler, and works across many
> projects.
>
> So I agree with you that this git-describe format is less convenient for
> readers, but my preferred solution is to use a different format, rather
> than try to teach every reading tool to be more clever.
>
> As far as I can tell, the main advantage of using "v2.11.0-rc3~3^2~1"
> over its hex id is that it gives a better sense in time of which Git
> version we're talking about. The date in the parentheses does something
> similar for wall-clock time, but it's left to the reader to map that to
> a Git version if they choose.
>
> Personally, I find the wall-clock time to be enough, since usually what
> I want to know is "how ancient is this". And in the rare instance that I
> care about the containing version, it's not a big deal to use "git tag
> --contains". If we really want to convey that information in the text,
> I think it would be reasonable to say something like:
>
> In commit 1234abcd (the subject line, 2016-01-01, v2.11.0), we did
> blah blah blah
>
> with a few simple rules:
>
> - only mention a single version, the oldest one that contains the
> commit[1]. If it's in v2.11.1, we can infer that it's in v2.12.0,
> etc.
>
> - only mention released commits; for the granularity we're talking
> about here, the distinction between v2.11.0 and v2.11.0-rc3 is not
> important
>
> - if it hasn't been in a released version, don't include a version at
> all.
>
> That's probably over-engineering, and I'm perfectly fine with the
> oid/subject/date format most people use. Just trying to give an option
> if people really think the tag name is useful.
>
> -Peff
>
> [1] I usually compute the containing version with:
>
> $ git help has
> 'has' is aliased to '!f() { git tag --contains "$@" | grep ^v | grep -v -- -rc | sort -V | head -1; }; f'
>
> though I suspect it could be done these days with fewer processes
> using "tag --sort".
prev parent reply other threads:[~2018-12-19 18:51 UTC|newest]
Thread overview: 17+ messages / expand[flat|nested] mbox.gz Atom feed top
2018-12-17 16:59 [PATCH] stripspace: allow -s/-c outside git repository Jonathan Nieder
2018-12-18 6:09 ` Martin Ågren
2018-12-18 12:00 ` Johannes Schindelin
2018-12-19 21:52 ` Martin Ågren
2018-12-18 11:58 ` Johannes Schindelin
2018-12-19 14:02 ` Referring to commits in commit messages Ævar Arnfjörð Bjarmason
2018-12-19 17:11 ` Duy Nguyen
2018-12-19 22:14 ` Jonathan Nieder
2018-12-20 0:18 ` Ævar Arnfjörð Bjarmason
2018-12-24 0:01 ` Jacob Keller
2018-12-19 17:38 ` SZEDER Gábor
2018-12-19 18:22 ` Jeff King
2018-12-19 18:39 ` Jonathan Nieder
2018-12-19 22:48 ` Jeff King
2018-12-19 23:29 ` Jonathan Nieder
2018-12-20 2:51 ` Jeff King
2018-12-19 18:52 ` Ævar Arnfjörð Bjarmason [this message]
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=875zvpfiy6.fsf@evledraar.gmail.com \
--to=avarab@gmail.com \
--cc=git@vger.kernel.org \
--cc=hanwen@google.com \
--cc=johannes.schindelin@gmx.de \
--cc=jrnieder@gmail.com \
--cc=peff@peff.net \
/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
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).