[darcs-users] short options and long names (VOTE!)

Andrew Pimlott 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
  patch bundle?

- 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 mailing list