[PATCH 3 of 5] shelve: use an --unshelve parameter instead of a command

[Martin Geisler]

Matt Mackall <mpm at selenic.com> writes:

> We've got a bunch of commands of the form foo/foos to make/list:
>
> 	tag/tags
> 	bookmark/bookmarks
> 	branch/branches

Most of our commands follow the 'hg <verb>' pattern: add, remove, push,
and pull. Some old commands use 'hg <noun>' instead, e.g., heads,
parents, and manifest.

The words above share an interesting feature: tag, bookmark, and branch
can all be used as both verbs and nouns. This makes the plural form
particularly nice for listing the objects and the singular form can be
read as a verb denoting the action you want Mercurial to do.

For this case, the noun is "shelf" and the verb is "shelve":

  http://www.merriam-webster.com/dictionary/shelf (plural: "shelves")
  http://www.merriam-webster.com/dictionary/shelve

That could be taken as an argument for having 'hg shelves' for listing
shelves and 'hg shelve' (verb) for making shelves.

In general, I think it is nice if the action implied by the verb isn't
changed completely by a flag. So 'hg revert --all' is good, the flag
extends the command to work on all files. By this logic, 'hg shelve
--unshelve' since the verb is reversed.

A command like 'hg bookmark --delete' is also good since "bookmark" can
be read as a noun. Without a flag "bookmark" becomes a verb and the
command does it's primary action: bookmarking a changeset. I'm not sure
if this logic I just made up extends to other commands.

> a) one command with suboptions (like resolve)
>
> 	hg shelve [name]
> 	hg shelve -l/--list
> 	hg shelve -u/--unshelve (or -p/--pop) [name]

I somewhat dislike the resolve command. Whenever I have to explain it to
somebody, I notice that the 'resolve' part becomes an almost irrelevant
part since all the good stuff is in its --list and --mark flags. That
is, I think it would be easier to explain fictive 'hg mergestate' and
'hg remerge' commands instead of the resolve command.

Bisect feels similarly flawed to me: its command line options are not
really options any longer. They could have been replaced with a
mandatory argument instead and the command would work the same. (This is
almost true: while testing this I learned that 'hg bisect' alone will
update to the revision that needs testing.)

> b) two commands (like tags/bookmarks)
>
> 	hg shelve [name]
> 	hg shelves
> 	hg shelve --u [name]
>
> c) three commands (like mq)
>
> 	hg shelve [name]
> 	hg shelves
> 	hg unshelve [name]
>
> My preference is for the first. If a year from now, we discover
> everyone wants unshelve and/or shelves, we can add that. But it's bit
> harder to take commands away.

I agree it sounds better to tell users "We've made things easier in this
release with a new command". Internally, I guess the code will look
about the same in both cases since we'll be marking flags or commands
with DEPRECATED and redirecting some logic.

-- 
Martin Geisler
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 835 bytes
Desc: not available
URL: <http://selenic.com/pipermail/mercurial-devel/attachments/20130921/cbc6753e/attachment.pgp>