Mercurial > hg
annotate mercurial/help/revsets.txt @ 30485:acd30a959980
dispatch: stop supporting non-use of @command
We said we'd delete this after 3.8. It's time.
author | Augie Fackler <augie@google.com> |
---|---|
date | Mon, 21 Nov 2016 21:51:23 -0500 |
parents | 5271ae666152 |
children | b8a188a6f191 |
rev | line source |
---|---|
11382 | 1 Mercurial supports a functional language for selecting a set of |
2 revisions. | |
3 | |
4 The language supports a number of predicates which are joined by infix | |
5 operators. Parenthesis can be used for grouping. | |
6 | |
15962
f7c8d6ee6056
revset: simplify help not about quoting
Matt Mackall <mpm@selenic.com>
parents:
14693
diff
changeset
|
7 Identifiers such as branch names may need quoting with single or |
f7c8d6ee6056
revset: simplify help not about quoting
Matt Mackall <mpm@selenic.com>
parents:
14693
diff
changeset
|
8 double quotes if they contain characters like ``-`` or if they match |
f7c8d6ee6056
revset: simplify help not about quoting
Matt Mackall <mpm@selenic.com>
parents:
14693
diff
changeset
|
9 one of the predefined predicates. |
12408
78a97859b90d
revset: support raw string literals
Brodie Rao <brodie@bitheap.org>
parents:
11944
diff
changeset
|
10 |
78a97859b90d
revset: support raw string literals
Brodie Rao <brodie@bitheap.org>
parents:
11944
diff
changeset
|
11 Special characters can be used in quoted identifiers by escaping them, |
78a97859b90d
revset: support raw string literals
Brodie Rao <brodie@bitheap.org>
parents:
11944
diff
changeset
|
12 e.g., ``\n`` is interpreted as a newline. To prevent them from being |
78a97859b90d
revset: support raw string literals
Brodie Rao <brodie@bitheap.org>
parents:
11944
diff
changeset
|
13 interpreted, strings can be prefixed with ``r``, e.g. ``r'...'``. |
11382 | 14 |
29989
5271ae666152
help: add sections for revsets
timeless <timeless@mozdev.org>
parents:
29988
diff
changeset
|
15 Prefix |
5271ae666152
help: add sections for revsets
timeless <timeless@mozdev.org>
parents:
29988
diff
changeset
|
16 ====== |
5271ae666152
help: add sections for revsets
timeless <timeless@mozdev.org>
parents:
29988
diff
changeset
|
17 |
11382 | 18 There is a single prefix operator: |
19 | |
20 ``not x`` | |
21 Changesets not in x. Short form is ``! x``. | |
22 | |
29989
5271ae666152
help: add sections for revsets
timeless <timeless@mozdev.org>
parents:
29988
diff
changeset
|
23 Infix |
5271ae666152
help: add sections for revsets
timeless <timeless@mozdev.org>
parents:
29988
diff
changeset
|
24 ===== |
5271ae666152
help: add sections for revsets
timeless <timeless@mozdev.org>
parents:
29988
diff
changeset
|
25 |
11382 | 26 These are the supported infix operators: |
27 | |
28 ``x::y`` | |
29 A DAG range, meaning all changesets that are descendants of x and | |
30 ancestors of y, including x and y themselves. If the first endpoint | |
31 is left out, this is equivalent to ``ancestors(y)``, if the second | |
11450
6bca9801c92a
revset: fix spelling typo
Julian Cowley <julian@lava.net>
parents:
11420
diff
changeset
|
32 is left out it is equivalent to ``descendants(x)``. |
11382 | 33 |
34 An alternative syntax is ``x..y``. | |
35 | |
36 ``x:y`` | |
37 All changesets with revision numbers between x and y, both | |
38 inclusive. Either endpoint can be left out, they default to 0 and | |
39 tip. | |
40 | |
41 ``x and y`` | |
42 The intersection of changesets in x and y. Short form is ``x & y``. | |
43 | |
44 ``x or y`` | |
45 The union of changesets in x and y. There are two alternative short | |
46 forms: ``x | y`` and ``x + y``. | |
47 | |
48 ``x - y`` | |
49 Changesets in x but not in y. | |
14692
0be6dc3d8083
help/revsets: clean up whitespace between paragraphs
Wagner Bruna <wbruna@softwareexpress.com.br>
parents:
14098
diff
changeset
|
50 |
29030
18c1b107898e
revsets: add docs for '%' operator
Sean Farley <sean@farley.io>
parents:
28986
diff
changeset
|
51 ``x % y`` |
18c1b107898e
revsets: add docs for '%' operator
Sean Farley <sean@farley.io>
parents:
28986
diff
changeset
|
52 Changesets that are ancestors of x but not ancestors of y (i.e. ::x - ::y). |
18c1b107898e
revsets: add docs for '%' operator
Sean Farley <sean@farley.io>
parents:
28986
diff
changeset
|
53 This is shorthand notation for ``only(x, y)`` (see below). The second |
18c1b107898e
revsets: add docs for '%' operator
Sean Farley <sean@farley.io>
parents:
28986
diff
changeset
|
54 argument is optional and, if left out, is equivalent to ``only(x)``. |
18c1b107898e
revsets: add docs for '%' operator
Sean Farley <sean@farley.io>
parents:
28986
diff
changeset
|
55 |
14070
305c97670d7a
revset: add ^ and ~ operators from parentrevspec extension
Kevin Gessner <kevin@kevingessner.com>
parents:
13937
diff
changeset
|
56 ``x^n`` |
305c97670d7a
revset: add ^ and ~ operators from parentrevspec extension
Kevin Gessner <kevin@kevingessner.com>
parents:
13937
diff
changeset
|
57 The nth parent of x, n == 0, 1, or 2. |
305c97670d7a
revset: add ^ and ~ operators from parentrevspec extension
Kevin Gessner <kevin@kevingessner.com>
parents:
13937
diff
changeset
|
58 For n == 0, x; for n == 1, the first parent of each changeset in x; |
305c97670d7a
revset: add ^ and ~ operators from parentrevspec extension
Kevin Gessner <kevin@kevingessner.com>
parents:
13937
diff
changeset
|
59 for n == 2, the second parent of changeset in x. |
305c97670d7a
revset: add ^ and ~ operators from parentrevspec extension
Kevin Gessner <kevin@kevingessner.com>
parents:
13937
diff
changeset
|
60 |
305c97670d7a
revset: add ^ and ~ operators from parentrevspec extension
Kevin Gessner <kevin@kevingessner.com>
parents:
13937
diff
changeset
|
61 ``x~n`` |
305c97670d7a
revset: add ^ and ~ operators from parentrevspec extension
Kevin Gessner <kevin@kevingessner.com>
parents:
13937
diff
changeset
|
62 The nth first ancestor of x; ``x~0`` is x; ``x~3`` is ``x^^^``. |
305c97670d7a
revset: add ^ and ~ operators from parentrevspec extension
Kevin Gessner <kevin@kevingessner.com>
parents:
13937
diff
changeset
|
63 |
29988
96358865edb3
help: move revsets.## documentation into infix section
timeless <timeless@mozdev.org>
parents:
29030
diff
changeset
|
64 ``x ## y`` |
96358865edb3
help: move revsets.## documentation into infix section
timeless <timeless@mozdev.org>
parents:
29030
diff
changeset
|
65 Concatenate strings and identifiers into one string. |
96358865edb3
help: move revsets.## documentation into infix section
timeless <timeless@mozdev.org>
parents:
29030
diff
changeset
|
66 |
96358865edb3
help: move revsets.## documentation into infix section
timeless <timeless@mozdev.org>
parents:
29030
diff
changeset
|
67 All other prefix, infix and postfix operators have lower priority than |
96358865edb3
help: move revsets.## documentation into infix section
timeless <timeless@mozdev.org>
parents:
29030
diff
changeset
|
68 ``##``. For example, ``a1 ## a2~2`` is equivalent to ``(a1 ## a2)~2``. |
96358865edb3
help: move revsets.## documentation into infix section
timeless <timeless@mozdev.org>
parents:
29030
diff
changeset
|
69 |
96358865edb3
help: move revsets.## documentation into infix section
timeless <timeless@mozdev.org>
parents:
29030
diff
changeset
|
70 For example:: |
96358865edb3
help: move revsets.## documentation into infix section
timeless <timeless@mozdev.org>
parents:
29030
diff
changeset
|
71 |
96358865edb3
help: move revsets.## documentation into infix section
timeless <timeless@mozdev.org>
parents:
29030
diff
changeset
|
72 [revsetalias] |
96358865edb3
help: move revsets.## documentation into infix section
timeless <timeless@mozdev.org>
parents:
29030
diff
changeset
|
73 issue(a1) = grep(r'\bissue[ :]?' ## a1 ## r'\b|\bbug\(' ## a1 ## r'\)') |
96358865edb3
help: move revsets.## documentation into infix section
timeless <timeless@mozdev.org>
parents:
29030
diff
changeset
|
74 |
96358865edb3
help: move revsets.## documentation into infix section
timeless <timeless@mozdev.org>
parents:
29030
diff
changeset
|
75 ``issue(1234)`` is equivalent to |
96358865edb3
help: move revsets.## documentation into infix section
timeless <timeless@mozdev.org>
parents:
29030
diff
changeset
|
76 ``grep(r'\bissue[ :]?1234\b|\bbug\(1234\)')`` |
96358865edb3
help: move revsets.## documentation into infix section
timeless <timeless@mozdev.org>
parents:
29030
diff
changeset
|
77 in this case. This matches against all of "issue 1234", "issue:1234", |
96358865edb3
help: move revsets.## documentation into infix section
timeless <timeless@mozdev.org>
parents:
29030
diff
changeset
|
78 "issue1234" and "bug(1234)". |
96358865edb3
help: move revsets.## documentation into infix section
timeless <timeless@mozdev.org>
parents:
29030
diff
changeset
|
79 |
29989
5271ae666152
help: add sections for revsets
timeless <timeless@mozdev.org>
parents:
29988
diff
changeset
|
80 Postfix |
5271ae666152
help: add sections for revsets
timeless <timeless@mozdev.org>
parents:
29988
diff
changeset
|
81 ======= |
5271ae666152
help: add sections for revsets
timeless <timeless@mozdev.org>
parents:
29988
diff
changeset
|
82 |
14070
305c97670d7a
revset: add ^ and ~ operators from parentrevspec extension
Kevin Gessner <kevin@kevingessner.com>
parents:
13937
diff
changeset
|
83 There is a single postfix operator: |
305c97670d7a
revset: add ^ and ~ operators from parentrevspec extension
Kevin Gessner <kevin@kevingessner.com>
parents:
13937
diff
changeset
|
84 |
305c97670d7a
revset: add ^ and ~ operators from parentrevspec extension
Kevin Gessner <kevin@kevingessner.com>
parents:
13937
diff
changeset
|
85 ``x^`` |
305c97670d7a
revset: add ^ and ~ operators from parentrevspec extension
Kevin Gessner <kevin@kevingessner.com>
parents:
13937
diff
changeset
|
86 Equivalent to ``x^1``, the first parent of each changeset in x. |
305c97670d7a
revset: add ^ and ~ operators from parentrevspec extension
Kevin Gessner <kevin@kevingessner.com>
parents:
13937
diff
changeset
|
87 |
29989
5271ae666152
help: add sections for revsets
timeless <timeless@mozdev.org>
parents:
29988
diff
changeset
|
88 Predicates |
5271ae666152
help: add sections for revsets
timeless <timeless@mozdev.org>
parents:
29988
diff
changeset
|
89 ========== |
11382 | 90 |
91 The following predicates are supported: | |
92 | |
12821
165079e564f0
revsets: generate predicate help dynamically
Patrick Mezard <pmezard@gmail.com>
parents:
12808
diff
changeset
|
93 .. predicatesmarker |
11382 | 94 |
29989
5271ae666152
help: add sections for revsets
timeless <timeless@mozdev.org>
parents:
29988
diff
changeset
|
95 Aliases |
5271ae666152
help: add sections for revsets
timeless <timeless@mozdev.org>
parents:
29988
diff
changeset
|
96 ======= |
5271ae666152
help: add sections for revsets
timeless <timeless@mozdev.org>
parents:
29988
diff
changeset
|
97 |
14098
9f5a0acb0056
revset aliases
Alexander Solovyov <alexander@solovyov.net>
parents:
14070
diff
changeset
|
98 New predicates (known as "aliases") can be defined, using any combination of |
9f5a0acb0056
revset aliases
Alexander Solovyov <alexander@solovyov.net>
parents:
14070
diff
changeset
|
99 existing predicates or other aliases. An alias definition looks like:: |
9f5a0acb0056
revset aliases
Alexander Solovyov <alexander@solovyov.net>
parents:
14070
diff
changeset
|
100 |
9f5a0acb0056
revset aliases
Alexander Solovyov <alexander@solovyov.net>
parents:
14070
diff
changeset
|
101 <alias> = <definition> |
9f5a0acb0056
revset aliases
Alexander Solovyov <alexander@solovyov.net>
parents:
14070
diff
changeset
|
102 |
14693
f9c056f48018
help/revsets: revset aliases can be defined on any config file
Wagner Bruna <wbruna@softwareexpress.com.br>
parents:
14692
diff
changeset
|
103 in the ``revsetalias`` section of a Mercurial configuration file. Arguments |
28986
97811ff79647
help: avoid using "$n" parameter in revsetalias example
Yuya Nishihara <yuya@tcha.org>
parents:
23742
diff
changeset
|
104 of the form `a1`, `a2`, etc. are substituted from the alias into the |
14693
f9c056f48018
help/revsets: revset aliases can be defined on any config file
Wagner Bruna <wbruna@softwareexpress.com.br>
parents:
14692
diff
changeset
|
105 definition. |
14098
9f5a0acb0056
revset aliases
Alexander Solovyov <alexander@solovyov.net>
parents:
14070
diff
changeset
|
106 |
9f5a0acb0056
revset aliases
Alexander Solovyov <alexander@solovyov.net>
parents:
14070
diff
changeset
|
107 For example, |
9f5a0acb0056
revset aliases
Alexander Solovyov <alexander@solovyov.net>
parents:
14070
diff
changeset
|
108 |
9f5a0acb0056
revset aliases
Alexander Solovyov <alexander@solovyov.net>
parents:
14070
diff
changeset
|
109 :: |
9f5a0acb0056
revset aliases
Alexander Solovyov <alexander@solovyov.net>
parents:
14070
diff
changeset
|
110 |
9f5a0acb0056
revset aliases
Alexander Solovyov <alexander@solovyov.net>
parents:
14070
diff
changeset
|
111 [revsetalias] |
9f5a0acb0056
revset aliases
Alexander Solovyov <alexander@solovyov.net>
parents:
14070
diff
changeset
|
112 h = heads() |
28986
97811ff79647
help: avoid using "$n" parameter in revsetalias example
Yuya Nishihara <yuya@tcha.org>
parents:
23742
diff
changeset
|
113 d(s) = sort(s, date) |
97811ff79647
help: avoid using "$n" parameter in revsetalias example
Yuya Nishihara <yuya@tcha.org>
parents:
23742
diff
changeset
|
114 rs(s, k) = reverse(sort(s, k)) |
14098
9f5a0acb0056
revset aliases
Alexander Solovyov <alexander@solovyov.net>
parents:
14070
diff
changeset
|
115 |
9f5a0acb0056
revset aliases
Alexander Solovyov <alexander@solovyov.net>
parents:
14070
diff
changeset
|
116 defines three aliases, ``h``, ``d``, and ``rs``. ``rs(0:tip, author)`` is |
9f5a0acb0056
revset aliases
Alexander Solovyov <alexander@solovyov.net>
parents:
14070
diff
changeset
|
117 exactly equivalent to ``reverse(sort(0:tip, author))``. |
9f5a0acb0056
revset aliases
Alexander Solovyov <alexander@solovyov.net>
parents:
14070
diff
changeset
|
118 |
29989
5271ae666152
help: add sections for revsets
timeless <timeless@mozdev.org>
parents:
29988
diff
changeset
|
119 Equivalents |
5271ae666152
help: add sections for revsets
timeless <timeless@mozdev.org>
parents:
29988
diff
changeset
|
120 =========== |
23742
3a4d8a6ce432
revset: introduce new operator "##" to concatenate strings/symbols at runtime
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents:
18469
diff
changeset
|
121 |
11382 | 122 Command line equivalents for :hg:`log`:: |
123 | |
124 -f -> ::. | |
125 -d x -> date(x) | |
126 -k x -> keyword(x) | |
127 -m -> merge() | |
128 -u x -> user(x) | |
129 -b x -> branch(x) | |
130 -P x -> !::x | |
131 -l x -> limit(expr, x) | |
132 | |
29989
5271ae666152
help: add sections for revsets
timeless <timeless@mozdev.org>
parents:
29988
diff
changeset
|
133 Examples |
5271ae666152
help: add sections for revsets
timeless <timeless@mozdev.org>
parents:
29988
diff
changeset
|
134 ======== |
5271ae666152
help: add sections for revsets
timeless <timeless@mozdev.org>
parents:
29988
diff
changeset
|
135 |
12659
5aa5cbaf6efc
revsets: add descriptions for sample queries in the help
Brodie Rao <brodie@bitheap.org>
parents:
12657
diff
changeset
|
136 Some sample queries: |
5aa5cbaf6efc
revsets: add descriptions for sample queries in the help
Brodie Rao <brodie@bitheap.org>
parents:
12657
diff
changeset
|
137 |
5aa5cbaf6efc
revsets: add descriptions for sample queries in the help
Brodie Rao <brodie@bitheap.org>
parents:
12657
diff
changeset
|
138 - Changesets on the default branch:: |
5aa5cbaf6efc
revsets: add descriptions for sample queries in the help
Brodie Rao <brodie@bitheap.org>
parents:
12657
diff
changeset
|
139 |
12808
74f6531581e8
help: use Windows cmd compatible quoting in revset help
Mads Kiilerich <mads@kiilerich.com>
parents:
12716
diff
changeset
|
140 hg log -r "branch(default)" |
12659
5aa5cbaf6efc
revsets: add descriptions for sample queries in the help
Brodie Rao <brodie@bitheap.org>
parents:
12657
diff
changeset
|
141 |
5aa5cbaf6efc
revsets: add descriptions for sample queries in the help
Brodie Rao <brodie@bitheap.org>
parents:
12657
diff
changeset
|
142 - Changesets on the default branch since tag 1.5 (excluding merges):: |
5aa5cbaf6efc
revsets: add descriptions for sample queries in the help
Brodie Rao <brodie@bitheap.org>
parents:
12657
diff
changeset
|
143 |
12808
74f6531581e8
help: use Windows cmd compatible quoting in revset help
Mads Kiilerich <mads@kiilerich.com>
parents:
12716
diff
changeset
|
144 hg log -r "branch(default) and 1.5:: and not merge()" |
11382 | 145 |
12660
6ed5ae6264c2
revsets: add a sample query to the help for getting active branches
Brodie Rao <brodie@bitheap.org>
parents:
12659
diff
changeset
|
146 - Open branch heads:: |
6ed5ae6264c2
revsets: add a sample query to the help for getting active branches
Brodie Rao <brodie@bitheap.org>
parents:
12659
diff
changeset
|
147 |
12808
74f6531581e8
help: use Windows cmd compatible quoting in revset help
Mads Kiilerich <mads@kiilerich.com>
parents:
12716
diff
changeset
|
148 hg log -r "head() and not closed()" |
12660
6ed5ae6264c2
revsets: add a sample query to the help for getting active branches
Brodie Rao <brodie@bitheap.org>
parents:
12659
diff
changeset
|
149 |
12659
5aa5cbaf6efc
revsets: add descriptions for sample queries in the help
Brodie Rao <brodie@bitheap.org>
parents:
12657
diff
changeset
|
150 - Changesets between tags 1.3 and 1.5 mentioning "bug" that affect |
12667
f5735bb80d77
revsets: fix stray * in help topic
Martin Geisler <mg@lazybytes.net>
parents:
12660
diff
changeset
|
151 ``hgext/*``:: |
12659
5aa5cbaf6efc
revsets: add descriptions for sample queries in the help
Brodie Rao <brodie@bitheap.org>
parents:
12657
diff
changeset
|
152 |
12808
74f6531581e8
help: use Windows cmd compatible quoting in revset help
Mads Kiilerich <mads@kiilerich.com>
parents:
12716
diff
changeset
|
153 hg log -r "1.3::1.5 and keyword(bug) and file('hgext/*')" |
12659
5aa5cbaf6efc
revsets: add descriptions for sample queries in the help
Brodie Rao <brodie@bitheap.org>
parents:
12657
diff
changeset
|
154 |
13937
5f126c01ebfa
help/revset: fix grammar
Idan Kamara <idankk86@gmail.com>
parents:
12821
diff
changeset
|
155 - Changesets committed in May 2008, sorted by user:: |
12659
5aa5cbaf6efc
revsets: add descriptions for sample queries in the help
Brodie Rao <brodie@bitheap.org>
parents:
12657
diff
changeset
|
156 |
12808
74f6531581e8
help: use Windows cmd compatible quoting in revset help
Mads Kiilerich <mads@kiilerich.com>
parents:
12716
diff
changeset
|
157 hg log -r "sort(date('May 2008'), user)" |
12659
5aa5cbaf6efc
revsets: add descriptions for sample queries in the help
Brodie Rao <brodie@bitheap.org>
parents:
12657
diff
changeset
|
158 |
5aa5cbaf6efc
revsets: add descriptions for sample queries in the help
Brodie Rao <brodie@bitheap.org>
parents:
12657
diff
changeset
|
159 - Changesets mentioning "bug" or "issue" that are not in a tagged |
5aa5cbaf6efc
revsets: add descriptions for sample queries in the help
Brodie Rao <brodie@bitheap.org>
parents:
12657
diff
changeset
|
160 release:: |
5aa5cbaf6efc
revsets: add descriptions for sample queries in the help
Brodie Rao <brodie@bitheap.org>
parents:
12657
diff
changeset
|
161 |
18469
ddbe689af784
doc: use "tag" revset predicate instead of "tagged" for example in help
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents:
15962
diff
changeset
|
162 hg log -r "(keyword(bug) or keyword(issue)) and not ancestors(tag())" |