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

Martin Geisler martin at geisler.net
Mon Sep 23 01:50:41 CDT 2013

Pierre-Yves David <pierre-yves.david at ens-lyon.org> writes:

> On 09/21/2013 06:22 PM, Martin Geisler wrote:
>> 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.
> There is active command and passive command. noun tend to be used by
> passive command (eg: hg heads vs hg listheads, hg summary vs hg
> summarize)
>> 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.
> As I noted in a previous email, `shelve` + `shelves` prevents the use
> of short form. There is only two commandes that suffer from this now:
> tag/tags and branch/branches.
> `tag` is a short form by itself and branch is not so frequently used
> in a sequence of action (in regard to usage of commit, or mq for
> example)

Yeah, it feels unfortunate to me to have one core command shadow another
like that, but I don't remember it being a problem in practice. I think
that is because it's rare that I create a tag and even rarer that I
delete one.

>> 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.
> If we used --apply instead of --unshelve. That would fit your
> description.

That would then be

  hg shelf --apply

for unshelving to go with the "singular noun" rule I made up previously.
That command is then a bit silly: we don't have other singular noun
commands since most of our things are plural.

I started thinking about this when looking at Git: there "stash" is used
as the command and that is both a singular noun and a verb, which makes

  git stash          # create a stash (verb, primary action)
  git stash --apply  # apply the stash (singular noun plus verb flag)

consistent with our bookmark command.

I don't really know how important these consistency rules are or how
long we can stretch the metaphors.

> (note saying I like it. Just saying that there is a flag based version
> that looks less silly on this aspect)

Yeah, it's a good point.

Martin Geisler

More information about the Mercurial-devel mailing list