From: Stefan Sperling <stsp@stsp.name>
Subject: Re: got {diff,log,update} -c KEYWORD (cf. svn revision keywords)
To: Mark Jamsek <mark@jamsek.com>
Cc: gameoftrees@openbsd.org
Date: Thu, 13 Jul 2023 10:03:02 +0200

On Thu, Jul 13, 2023 at 01:31:22PM +1000, Mark Jamsek wrote:
> # "branch-ref-abc-1" resolves to branch: return branch id
> got up -c branch-ref-abc-1
> 
> # "branch-ref-abc-1-2" does not resolve: parse -2 as the modifier
> # "branch-ref-abc-1" resolves to branch: return 2nd gen ancestor's id
> got up -c branch-ref-abc-1-2

The character - is particularly nasty because it often appears in
branch names in form of a hyphen.

Assume these two references exist:

  branch-ref-abc-2
  branch-ref-abc

And now someone decides to delete branch-ref-abc-2. The same command
which previously yielded branch-ref-abc-2 before this deletion will
now resolve to two commits prior to branch-ref-abc without any warning
or error, yielding a different result. What if something like this happens
in a script while nobody is watching?

If we used any of the reserved symbols as a separator we would avoid
this problem and Got would report that branch branch-ref-abc-2 does
not exist. Because now we can scan forward for this separator and parse
anything after it as a keyword, knowing the branch name with certainty.

The colon is one possible choice. Your proposed syntax would become:

  :{+,-}[N]

instead of the currently proposed:

  {+,-}[N]

With this, branch-ref-abc:-2 is no longer ambiguous.

Granted, users would now write -c BASE:-2 instead of the simpler -c BASE-2
but in return we obtain consistent behaviour when branches are deleted.

Alternatively, we could use any of these:

  ~{+,-}[N]
  ^{+,-}[N]
  ?{+,-}[N]
  *{+,-}[N]
  \\{+,-}[N]

At first sight, I prefer the colon.

> # "branch-ref-def+" does not resolve to branch: parse + as the modifier
> # branch-ref-def does not resolve:
> # return "reference branch-ref-def+ not found"
> got up -c branch-ref-def+
> 
> That said, while I find +/- to be very intuitive, we can always use
> something else; I was flirting with ":" and "^" at first, but I started
> using mblaze recently and it uses +/- for its mmsg(7) syntax to refer to
> the next and previous message of the current message, which is ".".
> And I thought it made perfect sense!
> 
> The third stage is to add the TIME syntax for temporal resolution.

A reserved separator would help with time and date syntax as well.
As an example, consider data specifications supported by cvs(1):

			1 month ago
			2 hours ago
			400000 seconds ago
			last year
			last Monday
			yesterday
			a fortnight ago
			3/31/92 10:00:07 PST
			January 23, 1987 10:05pm
			22:00 GMT

We could have something like this:

  got up -c main:"a fortnight ago"
  got up -c main:yesterday

I don't see a need for TIME or DATE keywords unless we end up in a
situation where a valid keyword also appear in a time specification.
Which is simple to avoid with a bit of planning ahead.