comparison mercurial/help/revsets.txt @ 28986:97811ff79647 stable

help: avoid using "$n" parameter in revsetalias example

Because parsing "$n" requires a crafted tokenizer, it exists only for backward
compatibility (as documented in revset._tokenizealias.) This patch updates the
examples so that users are encouraged to use symbolic names instead of "$n"s.

I'm going to implement alias expansion in templater, which won't support "$n"
parameters to make my life easier. Templater is more complicated than revset
because tokenizer and parser call each other.

28985:d2b29c848fcd

existing predicates or other aliases. An alias definition looks like::

  <alias> = <definition>

in the ``revsetalias`` section of a Mercurial configuration file. Arguments
of the form `$1`, `$2`, etc. are substituted from the alias into the
definition.

For example,

::

  [revsetalias]
  h = heads()
  d($1) = sort($1, date)
  rs($1, $2) = reverse(sort($1, $2))

defines three aliases, ``h``, ``d``, and ``rs``. ``rs(0:tip, author)`` is
exactly equivalent to ``reverse(sort(0:tip, author))``.

An infix operator ``##`` can concatenate strings and identifiers into
one string. For example::

  [revsetalias]
  issue($1) = grep(r'\bissue[ :]?' ## $1 ## r'\b|\bbug\(' ## $1 ## r'\)')

``issue(1234)`` is equivalent to ``grep(r'\bissue[ :]?1234\b|\bbug\(1234\)')``
in this case. This matches against all of "issue 1234", "issue:1234",
"issue1234" and "bug(1234)".

All other prefix, infix and postfix operators have lower priority than
``##``. For example, ``$1 ## $2~2`` is equivalent to ``($1 ## $2)~2``.

Command line equivalents for :hg:`log`::

  -f    ->  ::.
  -d x  ->  date(x)

28986:97811ff79647

existing predicates or other aliases. An alias definition looks like::

  <alias> = <definition>

in the ``revsetalias`` section of a Mercurial configuration file. Arguments
of the form `a1`, `a2`, etc. are substituted from the alias into the
definition.

For example,

::

  [revsetalias]
  h = heads()
  d(s) = sort(s, date)
  rs(s, k) = reverse(sort(s, k))

defines three aliases, ``h``, ``d``, and ``rs``. ``rs(0:tip, author)`` is
exactly equivalent to ``reverse(sort(0:tip, author))``.

An infix operator ``##`` can concatenate strings and identifiers into
one string. For example::

  [revsetalias]
  issue(a1) = grep(r'\bissue[ :]?' ## a1 ## r'\b|\bbug\(' ## a1 ## r'\)')

``issue(1234)`` is equivalent to ``grep(r'\bissue[ :]?1234\b|\bbug\(1234\)')``
in this case. This matches against all of "issue 1234", "issue:1234",
"issue1234" and "bug(1234)".

All other prefix, infix and postfix operators have lower priority than
``##``. For example, ``a1 ## a2~2`` is equivalent to ``(a1 ## a2)~2``.

Command line equivalents for :hg:`log`::

  -f    ->  ::.
  -d x  ->  date(x)