1 Mercurial supports several ways to specify revisions.

     2 

     3 Specifying single revisions

     4 ===========================

     5 

     6 A plain integer is treated as a revision number. Negative integers are

     7 treated as sequential offsets from the tip, with -1 denoting the tip,

     8 -2 denoting the revision prior to the tip, and so forth.

     9 

    10 A 40-digit hexadecimal string is treated as a unique revision identifier.

    11 A hexadecimal string less than 40 characters long is treated as a

    12 unique revision identifier and is referred to as a short-form

    13 identifier. A short-form identifier is only valid if it is the prefix

    14 of exactly one full-length identifier.

    15 

    16 Any other string is treated as a bookmark, tag, or branch name. A

    17 bookmark is a movable pointer to a revision. A tag is a permanent name

    18 associated with a revision. A branch name denotes the tipmost open branch head

    19 of that branch - or if they are all closed, the tipmost closed head of the

    20 branch. Bookmark, tag, and branch names must not contain the ":" character.

    21 

    22 The reserved name "tip" always identifies the most recent revision.

    23 

    24 The reserved name "null" indicates the null revision. This is the

    25 revision of an empty repository, and the parent of revision 0.

    26 

    27 The reserved name "." indicates the working directory parent. If no

    28 working directory is checked out, it is equivalent to null. If an

    29 uncommitted merge is in progress, "." is the revision of the first

    30 parent.

    31 

    32 Finally, commands that expect a single revision (like ``hg update``) also

    33 accept revsets (see below for details). When given a revset, they use the

    34 last revision of the revset. A few commands accept two single revisions

    35 (like ``hg diff``). When given a revset, they use the first and the last

    36 revisions of the revset.

    37 

    38 Specifying multiple revisions

    39 =============================

    40 

    41 Mercurial supports a functional language for selecting a set of

    42 revisions. Expressions in this language are called revsets.

    43 

    44 The language supports a number of predicates which are joined by infix

    45 operators. Parenthesis can be used for grouping.

    46 

    47 Identifiers such as branch names may need quoting with single or

    48 double quotes if they contain characters like ``-`` or if they match

    49 one of the predefined predicates.

    50 

    51 Special characters can be used in quoted identifiers by escaping them,

    52 e.g., ``\n`` is interpreted as a newline. To prevent them from being

    53 interpreted, strings can be prefixed with ``r``, e.g. ``r'...'``.

    54 

    55 Operators

    56 =========

    57 

    58 There is a single prefix operator:

    59 

    60 ``not x``

    61   Changesets not in x. Short form is ``! x``.

    62 

    63 These are the supported infix operators:

    64 

    65 ``x::y``

    66   A DAG range, meaning all changesets that are descendants of x and

    67   ancestors of y, including x and y themselves. If the first endpoint

    68   is left out, this is equivalent to ``ancestors(y)``, if the second

    69   is left out it is equivalent to ``descendants(x)``.

    70 

    71   An alternative syntax is ``x..y``.

    72 

    73 ``x:y``

    74   All changesets with revision numbers between x and y, both

    75   inclusive. Either endpoint can be left out, they default to 0 and

    76   tip.

    77 

    78 ``x and y``

    79   The intersection of changesets in x and y. Short form is ``x & y``.

    80 

    81 ``x or y``

    82   The union of changesets in x and y. There are two alternative short

    83   forms: ``x | y`` and ``x + y``.

    84 

    85 ``x - y``

    86   Changesets in x but not in y.

    87 

    88 ``x % y``

    89   Changesets that are ancestors of x but not ancestors of y (i.e. ::x - ::y).

    90   This is shorthand notation for ``only(x, y)`` (see below). The second

    91   argument is optional and, if left out, is equivalent to ``only(x)``.

    92 

    93 ``x^n``

    94   The nth parent of x, n == 0, 1, or 2.

    95   For n == 0, x; for n == 1, the first parent of each changeset in x;

    96   for n == 2, the second parent of changeset in x.

    97 

    98 ``x~n``

    99   The nth first ancestor of x; ``x~0`` is x; ``x~3`` is ``x^^^``.

   100   For n < 0, the nth unambiguous descendent of x.

   101 

   102 ``x ## y``

   103   Concatenate strings and identifiers into one string.

   104 

   105   All other prefix, infix and postfix operators have lower priority than

   106   ``##``. For example, ``a1 ## a2~2`` is equivalent to ``(a1 ## a2)~2``.

   107 

   108   For example::

   109 

   110     [revsetalias]

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

   112 

   113   ``issue(1234)`` is equivalent to

   114   ``grep(r'\bissue[ :]?1234\b|\bbug\(1234\)')``

   115   in this case. This matches against all of "issue 1234", "issue:1234",

   116   "issue1234" and "bug(1234)".

   117 

   118 There is a single postfix operator:

   119 

   120 ``x^``

   121   Equivalent to ``x^1``, the first parent of each changeset in x.

   122 

   123 Patterns

   124 ========

   125 

   126 Where noted, predicates that perform string matching can accept a pattern

   127 string. The pattern may be either a literal, or a regular expression. If the

   128 pattern starts with ``re:``, the remainder of the pattern is treated as a

   129 regular expression. Otherwise, it is treated as a literal. To match a pattern

   130 that actually starts with ``re:``, use the prefix ``literal:``.

   131 

   132 Matching is case-sensitive, unless otherwise noted.  To perform a case-

   133 insensitive match on a case-sensitive predicate, use a regular expression,

   134 prefixed with ``(?i)``.

   135 

   136 For example, ``tag(r're:(?i)release')`` matches "release" or "RELEASE"

   137 or "Release", etc.

   138 

   139 Predicates

   140 ==========

   141 

   142 The following predicates are supported:

   143 

   144 .. predicatesmarker

   145 

   146 Aliases

   147 =======

   148 

   149 New predicates (known as "aliases") can be defined, using any combination of

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

   151 

   152   <alias> = <definition>

   153 

   154 in the ``revsetalias`` section of a Mercurial configuration file. Arguments

   155 of the form `a1`, `a2`, etc. are substituted from the alias into the

   156 definition.

   157 

   158 For example,

   159 

   160 ::

   161 

   162   [revsetalias]

   163   h = heads()

   164   d(s) = sort(s, date)

   165   rs(s, k) = reverse(sort(s, k))

   166 

   167 defines three aliases, ``h``, ``d``, and ``rs``. ``rs(0:tip, author)`` is

   168 exactly equivalent to ``reverse(sort(0:tip, author))``.

   169 

   170 Equivalents

   171 ===========

   172 

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

   174 

   175   -f    ->  ::.

   176   -d x  ->  date(x)

   177   -k x  ->  keyword(x)

   178   -m    ->  merge()

   179   -u x  ->  user(x)

   180   -b x  ->  branch(x)

   181   -P x  ->  !::x

   182   -l x  ->  limit(expr, x)

   183 

   184 Examples

   185 ========

   186 

   187 Some sample queries:

   188 

   189 - Changesets on the default branch::

   190 

   191     hg log -r "branch(default)"

   192 

   193 - Changesets on the default branch since tag 1.5 (excluding merges)::

   194 

   195     hg log -r "branch(default) and 1.5:: and not merge()"

   196 

   197 - Open branch heads::

   198 

   199     hg log -r "head() and not closed()"

   200 

   201 - Changesets between tags 1.3 and 1.5 mentioning "bug" that affect

   202   ``hgext/*``::

   203 

   204     hg log -r "1.3::1.5 and keyword(bug) and file('hgext/*')"

   205 

   206 - Changesets committed in May 2008, sorted by user::

   207 

   208     hg log -r "sort(date('May 2008'), user)"

   209 

   210 - Changesets mentioning "bug" or "issue" that are not in a tagged

   211   release::

   212 

   213     hg log -r "(keyword(bug) or keyword(issue)) and not ancestors(tag())"

   214 

   215 - Update to the commit that bookmark @ is pointing to, without activating the

   216   bookmark (this works because the last revision of the revset is used)::

   217 

   218     hg update :@

   219 

   220 - Show diff between tags 1.3 and 1.5 (this works because the first and the

   221   last revisions of the revset are used)::

   222 

   223     hg diff -r 1.3::1.5