(The description below is my speculation on how darcs is intended to
work, so If I'm wrong, I'd like to be corrected.)

To select a subset of patches from the history, the darcs commands
have 3 groups of command-line flags, with the following meanings:

  * select one patch
    --patch
    --match
    --tag
    --index=N (used in dist, annotate, show contents, show files)

  * select several patches
    --patches
    --matches
    --tags

  * specify range limit
    --from-{patch,match,tag} (from-flags)
    --to-{patch,match,tag} (to-flags)
    --index=N-M (used in diff, changes)
    --last=N (with the meaning of --index=1-N)

The default values for the from- and to-options are the beginning and
the end of patch history, respectively.  When only a to-flag is set,
it means "from the beginning to a patch", while with the only
from-flag, the meaning is "from a patch to the end (current state)".

Of several patches that match the given condition, the last is taken,
because the patch history is processed in the reverse order.

The things I've found out to be wrong:

1. diff incorrectly interprets to-flags, giving the reverse of the
diff with the identical from-flag.  If the flags are interpreted as
specified above, the resulting diff should be between the state after
the matching patch and initial (empty) state.  While this still
doesn't make much sence, at least it will make for more consistent
behaviour.

2. --index and --last don't play well together, when given both flags,
--index=N-M and --last=L, darcs interprets them as --index=N-L no
matter what order the flags were in, which isn't the most expected
thing to do.  It would be more expected that of the both flags only
the last was taken (not to confuse with the --last flag).

3. --index and --last don't play well together with the from- and
to-flags.  There's no simple intuitive way to interpret the combined
meaning if the flags of both groups are given.  This can be solved by
introducing --to-index and --from-index flags, which will not only
blend nicely with the rest of flags, but also are more flexible than
--index and --last.

4. The --index flag is overloaded to fall into two groups of patches,
'select one patch' and 'select range of patches'.  From the UI
perspective, it's better to have only one meaning for each flag.
This, again, can be solved by deprecating a range form of --index in
favour of better alternatives.

5. get and put have --to-match and --to-patch, but no --to-tag.
Instead, --tag is used, which doesn't belong there.

6. dist has one patch selection flags (--match, --patch and --tag),
which doesn't make sense for me.  How does one distribute a single
patch? Perhaps the to-flags were meant?

On Fri, Apr 15, 2011 at 00:13:51 +0000, Alexey Levan wrote:
> (The description below is my speculation on how darcs is intended to
> work, so If I'm wrong, I'd like to be corrected.)

Yes! I like that somebody is trying to think about the matchers
in a comprehensive/integrated way.

Alexey: I haven't had time to look through the issues you raised
in detail yet, but could you search the tracker for issues with
topic "Matcher"?  It'd be great if you could find duplicates to
reduce the amount of ground we need to cover.

I remember --last is actually quite confusing for people
(cf --max-count).

We also have the issue of backwards compatibility to think about but if
it's just down to a question of avoiding confused users, I think because
Darcs has been so good at avoiding success, we can afford to be
relatively bold about changing things in the interest of a better UI in
the long term... within reason, of course!

-- 
Eric Kow <http://www.nltg.brighton.ac.uk/home/Eric.Kow>
For a faster response, try +44 (0)1273 64 2905 or
xmpp:kowey@jabber.fr (Jabber or Google Talk only)

> Alexey: I haven't had time to look through the issues you raised
> in detail yet, but could you search the tracker for issues with
> topic "Matcher"?  It'd be great if you could find duplicates to
> reduce the amount of ground we need to cover.
>
> I remember --last is actually quite confusing for people
> (cf --max-count).

Although I didn't find any duplicate issues, there're two relevant
ones, namely issue1116 and issue1158.  I think it's worth to discuss
them here.

In the issue1116, it is proposed to reject multiple from-matchers on
the command line, which, in my opinion, is a wrong thing to do.  One
of the key UI principles is the principle of least astonishment, which
(roughly) states that the thing should be as you expect them to be.
The traditional rule for command-line flags is to discard everything
but the last flag, and I see no reason not to follow it.  What still
may surprise the user is that several flags (say, --patch and --match)
are used as one and override each other, but that's at least
reasonable considering how closely they are related.

In the issue1158, another way to combine different matches is
discussed: instead of discarding all but the last flag of a group,
it's proposed to 'add' those matches.  But again, I see a problem
here.  There's two ways to add matchers that have two different
meanings: you can either add the matchers themselves, which gives an
intersection of the resulting patches, or you can add those patches,
i. e. union them.  I don't have a preference for either of meaning,
and expect the users not to have it either.  Thus, again, we have a
violation of the principle of least astonishment with the 50%
probability.  I think it's better to stick with the traditional way
and take only the last option.  There's already a way to explicitly
apply boolean logic in the matcher, having an additional arbitrary
implicit way will do more harm than good.

> We also have the issue of backwards compatibility to think about but if
> it's just down to a question of avoiding confused users, I think because
> Darcs has been so good at avoiding success, we can afford to be
> relatively bold about changing things in the interest of a better UI in
> the long term... within reason, of course!

I think the right(tm) thing to do here is to give a deprecation
warning about the "wrong" flags for a couple of releases, and then get
rid of them.  This will lead to a cleaner UI and code in future
without harming the users too much.

The whole command line flag thing needs an all-in-one rethink IMHO

Added to http://darcs.net/Ideas/Flags