Are Mercurial Queue specific commands equivalent to Mercurial commands with a --mq parameter?

Question

I'm trying to learn Mercurial Queues and I'm confused by there being both a bunch of "hg q*" commands and also many normal hg commands with the "--mq" parameter. I think that the --mq parameter is meant to replace some of the q* commands, but I'm not sure. There doesn't seem to be a tutorial or documentation on the (new?) preferred methods.

Answer 1

The --mq option affects all commands that take a repository as an argument -- it actually changes the targeted repo to be $(hg root)/.hg/patches, so it's effectively the same as running any mercurial command like this:

hg --repository $(hg root)/.hg/patches ....

Resultingly, every command that has a -R/--repository option has a --mq option and didn't need to be modified to get one. Any command you've previously used in mercurial: commit, push, pull, summary, id, etc. can take --mq. Here's the relevant python code:

def mqcommand(orig, ui, repo, *args, **kwargs):
    """Add --mq option to operate on patch repository instead of main"""

    # some commands do not like getting unknown options
    mq = kwargs.pop('mq', None)

    if not mq:
        return orig(ui, repo, *args, **kwargs)

    q = repo.mq
    r = q.qrepo()
    if not r:
        raise util.Abort(_('no queue repository'))
    return orig(r.ui, r, *args, **kwargs)

Answer 2

The commands that the --mq flag make unnecessary have been marked deprecated so that they disappear from hg help mq. This is why qcommit and qinit no long show up.

You can still do hg qcommit to see the help for the command if you are curious.

Personally, I don't like the --mq flag. Instead I use a shell alias:

mq='hg -R $(hg root)/.hg/patches'

and then I can do mq status, mq commit, mq push, etc. I find that the distinction between the hg and mq command names match how I think of the operations. Note that this simple alias doesn't take multiple queues into account, so if you use hg qqueue, then you'll have to extend it a bit.