[darcs-users] short options and long names (VOTE!)
andrew at pimlott.net
Tue Jul 27 07:11:50 UTC 2004
[Replying to old mail.]
On Fri, Jun 11, 2004 at 06:37:28AM -0400, David Roundy wrote:
> I've implemented this suggestion, since it seemed good to me. Flags now
> specify either a single patch (--patch), several patches (--patches) or
> one end of a patch range (--from-patch and --to-patch).
I started trying to update the documentation for this, but I found that
I still don't understand these options. Let me go through the commands
that use them and explain my confusion. As preface, I think some of it
stems from the fact that a range of patches is an ill-defined concept,
since patches are not fully ordered, even though it is practically
useful (at least today). I think darcs should make a decision about
where this concept is useful and supported, and deprecate its use
outside of those places. Similarly, --patch isn't well-defined, since
it takes the "last" matching patch.
- get takes --patch. However, this really specifies a range that
implicitly starts at the beginning. Maybe this should be made
explicit with --to-patch.
- pull, push, and send take --patches (implying these patches and their
dependents). The discrepancy with get jumps out at me: if it makes
sense to get a range with get, why not with pull? Or ask the question
the other way around.
- apply takes nothing. Might you ever want to pick from a sent
- rollback, unrecord, and unpull take --patch. Is there any particular
reason not to allow multiple patches here? In fact, I would argue
that the current semantic is closer to --patches, since you are
prompted with a series of patches until you say 'y'.
- rerecord takes --patch. I haven't used this much, but this seems
right, except that using --tag here would be bizarre. (Hmm... you
might want to combine multiple patches into one, in which case you
might want --patches to specify the patches, and --patch-name to name
the new patch.)
- changes takes --from-patch, but not --to-patch. What's up with that?
A range is probably ok for an informational command like changes.
However you probably often want something different: the set of
changes in tag a, but not tag b. AFAICT there's no way to get that.
Also, you might want to see the changes from a single patch (more
plausible with diff, but even with changes you can see the files
affected), so maybe this command should also take --patch. Or should
it be --patches?
BTW, --from-patch does not include the specified patch, which I think
is usually counterintuitive, and prevents you from including the first
patch. I think --from and --to should both be inclusive (probably
even if they define a reverse range).
- diff takes --from-patch and --to-patch. Similar to changes.
- annotate takes --patch. This has totally different meanings in the
two behaviors of annotate, which is way confusing. In patch output
mode, it should probably be similar to changes. In annotate mode,
--patch is probably ok, although maybe it should be --to-patch.
My thoughts aren't entirely coherent right now, but here is a proposal
to think about:
- Eliminate the singular/plural distinction and just use --patch. This
is always plural; in diff and rerecord, it is an error if this
designates multiple patches (or maybe they should just be exceptions,
and take the latest match). (BTW, --tag should probably also be
plural for consistency, even though the distinction will almost never
arise.) Maybe make --patch and --patches synonyms, for when one or
the other is more natural, but emphasize that they are the same.
- Remove all [pm]atch options from get. You can only get tags. I
assume (didn't test) that --tag is interpreted as a range, just like
--patch is. If so, this is a bug: it should get exactly that tag.
(The two behaviors are usually indistinguishable, but I think if tags
were created in separate repositories, they might not be.)
- Add --patch to apply. Why not?
- rollback, unrecord, and unpull all keep going after the user presses
'y'. Add a 'd'one command to stop.
- Eliminate --tag from rerecord.
- changes and diff both take --from-patch, --to-patch, and --patch.
- Put the patch output mode of annotate into changes.
- Use --to-patch for annotate mode of annotate.
BTW, I like the --last option that was recently added. However, I don't
think it should fail if more than the number of patches in the repo is
specified; it should just print what it has.
PS. I will answer email faster this time. I was moving last month.
More information about the darcs-users