Mercurial > hg
annotate mercurial/help/revsets.txt @ 30731:b8a188a6f191
help: merge the various operator sections of revsets, filesets and templates
Having sections for specific operator types assumes the user already knows what
type of operators are supported. By having a common heading, the user can
simply lookup help for "(revsets|filesets|templates).operators".
author | Matt Harbison <matt_harbison@yahoo.com> |
---|---|
date | Sun, 08 Jan 2017 12:05:10 -0500 |
parents | 5271ae666152 |
children |
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 |
30731
b8a188a6f191
help: merge the various operator sections of revsets, filesets and templates
Matt Harbison <matt_harbison@yahoo.com>
parents:
29989
diff
changeset
|
15 Operators |
b8a188a6f191
help: merge the various operator sections of revsets, filesets and templates
Matt Harbison <matt_harbison@yahoo.com>
parents:
29989
diff
changeset
|
16 ========= |
29989
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 | |
23 These are the supported infix operators: | |
24 | |
25 ``x::y`` | |
26 A DAG range, meaning all changesets that are descendants of x and | |
27 ancestors of y, including x and y themselves. If the first endpoint | |
28 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
|
29 is left out it is equivalent to ``descendants(x)``. |
11382 | 30 |
31 An alternative syntax is ``x..y``. | |
32 | |
33 ``x:y`` | |
34 All changesets with revision numbers between x and y, both | |
35 inclusive. Either endpoint can be left out, they default to 0 and | |
36 tip. | |
37 | |
38 ``x and y`` | |
39 The intersection of changesets in x and y. Short form is ``x & y``. | |
40 | |
41 ``x or y`` | |
42 The union of changesets in x and y. There are two alternative short | |
43 forms: ``x | y`` and ``x + y``. | |
44 | |
45 ``x - y`` | |
46 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
|
47 |
29030
18c1b107898e
revsets: add docs for '%' operator
Sean Farley <sean@farley.io>
parents:
28986
diff
changeset
|
48 ``x % y`` |
18c1b107898e
revsets: add docs for '%' operator
Sean Farley <sean@farley.io>
parents:
28986
diff
changeset
|
49 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
|
50 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
|
51 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
|
52 |
14070
305c97670d7a
revset: add ^ and ~ operators from parentrevspec extension
Kevin Gessner <kevin@kevingessner.com>
parents:
13937
diff
changeset
|
53 ``x^n`` |
305c97670d7a
revset: add ^ and ~ operators from parentrevspec extension
Kevin Gessner <kevin@kevingessner.com>
parents:
13937
diff
changeset
|
54 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
|
55 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
|
56 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
|
57 |
305c97670d7a
revset: add ^ and ~ operators from parentrevspec extension
Kevin Gessner <kevin@kevingessner.com>
parents:
13937
diff
changeset
|
58 ``x~n`` |
305c97670d7a
revset: add ^ and ~ operators from parentrevspec extension
Kevin Gessner <kevin@kevingessner.com>
parents:
13937
diff
changeset
|
59 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
|
60 |
29988
96358865edb3
help: move revsets.## documentation into infix section
timeless <timeless@mozdev.org>
parents:
29030
diff
changeset
|
61 ``x ## y`` |
96358865edb3
help: move revsets.## documentation into infix section
timeless <timeless@mozdev.org>
parents:
29030
diff
changeset
|
62 Concatenate strings and identifiers into one string. |
96358865edb3
help: move revsets.## documentation into infix section
timeless <timeless@mozdev.org>
parents:
29030
diff
changeset
|
63 |
96358865edb3
help: move revsets.## documentation into infix section
timeless <timeless@mozdev.org>
parents:
29030
diff
changeset
|
64 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
|
65 ``##``. 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
|
66 |
96358865edb3
help: move revsets.## documentation into infix section
timeless <timeless@mozdev.org>
parents:
29030
diff
changeset
|
67 For example:: |
96358865edb3
help: move revsets.## documentation into infix section
timeless <timeless@mozdev.org>
parents:
29030
diff
changeset
|
68 |
96358865edb3
help: move revsets.## documentation into infix section
timeless <timeless@mozdev.org>
parents:
29030
diff
changeset
|
69 [revsetalias] |
96358865edb3
help: move revsets.## documentation into infix section
timeless <timeless@mozdev.org>
parents:
29030
diff
changeset
|
70 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
|
71 |
96358865edb3
help: move revsets.## documentation into infix section
timeless <timeless@mozdev.org>
parents:
29030
diff
changeset
|
72 ``issue(1234)`` is equivalent to |
96358865edb3
help: move revsets.## documentation into infix section
timeless <timeless@mozdev.org>
parents:
29030
diff
changeset
|
73 ``grep(r'\bissue[ :]?1234\b|\bbug\(1234\)')`` |
96358865edb3
help: move revsets.## documentation into infix section
timeless <timeless@mozdev.org>
parents:
29030
diff
changeset
|
74 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
|
75 "issue1234" and "bug(1234)". |
96358865edb3
help: move revsets.## documentation into infix section
timeless <timeless@mozdev.org>
parents:
29030
diff
changeset
|
76 |
14070
305c97670d7a
revset: add ^ and ~ operators from parentrevspec extension
Kevin Gessner <kevin@kevingessner.com>
parents:
13937
diff
changeset
|
77 There is a single postfix operator: |
305c97670d7a
revset: add ^ and ~ operators from parentrevspec extension
Kevin Gessner <kevin@kevingessner.com>
parents:
13937
diff
changeset
|
78 |
305c97670d7a
revset: add ^ and ~ operators from parentrevspec extension
Kevin Gessner <kevin@kevingessner.com>
parents:
13937
diff
changeset
|
79 ``x^`` |
305c97670d7a
revset: add ^ and ~ operators from parentrevspec extension
Kevin Gessner <kevin@kevingessner.com>
parents:
13937
diff
changeset
|
80 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
|
81 |
29989
5271ae666152
help: add sections for revsets
timeless <timeless@mozdev.org>
parents:
29988
diff
changeset
|
82 Predicates |
5271ae666152
help: add sections for revsets
timeless <timeless@mozdev.org>
parents:
29988
diff
changeset
|
83 ========== |
11382 | 84 |
85 The following predicates are supported: | |
86 | |
12821
165079e564f0
revsets: generate predicate help dynamically
Patrick Mezard <pmezard@gmail.com>
parents:
12808
diff
changeset
|
87 .. predicatesmarker |
11382 | 88 |
29989
5271ae666152
help: add sections for revsets
timeless <timeless@mozdev.org>
parents:
29988
diff
changeset
|
89 Aliases |
5271ae666152
help: add sections for revsets
timeless <timeless@mozdev.org>
parents:
29988
diff
changeset
|
90 ======= |
5271ae666152
help: add sections for revsets
timeless <timeless@mozdev.org>
parents:
29988
diff
changeset
|
91 |
14098
9f5a0acb0056
revset aliases
Alexander Solovyov <alexander@solovyov.net>
parents:
14070
diff
changeset
|
92 New predicates (known as "aliases") can be defined, using any combination of |
9f5a0acb0056
revset aliases
Alexander Solovyov <alexander@solovyov.net>
parents:
14070
diff
changeset
|
93 existing predicates or other aliases. An alias definition looks like:: |
9f5a0acb0056
revset aliases
Alexander Solovyov <alexander@solovyov.net>
parents:
14070
diff
changeset
|
94 |
9f5a0acb0056
revset aliases
Alexander Solovyov <alexander@solovyov.net>
parents:
14070
diff
changeset
|
95 <alias> = <definition> |
9f5a0acb0056
revset aliases
Alexander Solovyov <alexander@solovyov.net>
parents:
14070
diff
changeset
|
96 |
14693
f9c056f48018
help/revsets: revset aliases can be defined on any config file
Wagner Bruna <wbruna@softwareexpress.com.br>
parents:
14692
diff
changeset
|
97 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
|
98 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
|
99 definition. |
14098
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 For example, |
9f5a0acb0056
revset aliases
Alexander Solovyov <alexander@solovyov.net>
parents:
14070
diff
changeset
|
102 |
9f5a0acb0056
revset aliases
Alexander Solovyov <alexander@solovyov.net>
parents:
14070
diff
changeset
|
103 :: |
9f5a0acb0056
revset aliases
Alexander Solovyov <alexander@solovyov.net>
parents:
14070
diff
changeset
|
104 |
9f5a0acb0056
revset aliases
Alexander Solovyov <alexander@solovyov.net>
parents:
14070
diff
changeset
|
105 [revsetalias] |
9f5a0acb0056
revset aliases
Alexander Solovyov <alexander@solovyov.net>
parents:
14070
diff
changeset
|
106 h = heads() |
28986
97811ff79647
help: avoid using "$n" parameter in revsetalias example
Yuya Nishihara <yuya@tcha.org>
parents:
23742
diff
changeset
|
107 d(s) = sort(s, date) |
97811ff79647
help: avoid using "$n" parameter in revsetalias example
Yuya Nishihara <yuya@tcha.org>
parents:
23742
diff
changeset
|
108 rs(s, k) = reverse(sort(s, k)) |
14098
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 defines three aliases, ``h``, ``d``, and ``rs``. ``rs(0:tip, author)`` is |
9f5a0acb0056
revset aliases
Alexander Solovyov <alexander@solovyov.net>
parents:
14070
diff
changeset
|
111 exactly equivalent to ``reverse(sort(0:tip, author))``. |
9f5a0acb0056
revset aliases
Alexander Solovyov <alexander@solovyov.net>
parents:
14070
diff
changeset
|
112 |
29989
5271ae666152
help: add sections for revsets
timeless <timeless@mozdev.org>
parents:
29988
diff
changeset
|
113 Equivalents |
5271ae666152
help: add sections for revsets
timeless <timeless@mozdev.org>
parents:
29988
diff
changeset
|
114 =========== |
23742
3a4d8a6ce432
revset: introduce new operator "##" to concatenate strings/symbols at runtime
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents:
18469
diff
changeset
|
115 |
11382 | 116 Command line equivalents for :hg:`log`:: |
117 | |
118 -f -> ::. | |
119 -d x -> date(x) | |
120 -k x -> keyword(x) | |
121 -m -> merge() | |
122 -u x -> user(x) | |
123 -b x -> branch(x) | |
124 -P x -> !::x | |
125 -l x -> limit(expr, x) | |
126 | |
29989
5271ae666152
help: add sections for revsets
timeless <timeless@mozdev.org>
parents:
29988
diff
changeset
|
127 Examples |
5271ae666152
help: add sections for revsets
timeless <timeless@mozdev.org>
parents:
29988
diff
changeset
|
128 ======== |
5271ae666152
help: add sections for revsets
timeless <timeless@mozdev.org>
parents:
29988
diff
changeset
|
129 |
12659
5aa5cbaf6efc
revsets: add descriptions for sample queries in the help
Brodie Rao <brodie@bitheap.org>
parents:
12657
diff
changeset
|
130 Some sample queries: |
5aa5cbaf6efc
revsets: add descriptions for sample queries in the help
Brodie Rao <brodie@bitheap.org>
parents:
12657
diff
changeset
|
131 |
5aa5cbaf6efc
revsets: add descriptions for sample queries in the help
Brodie Rao <brodie@bitheap.org>
parents:
12657
diff
changeset
|
132 - Changesets on the default branch:: |
5aa5cbaf6efc
revsets: add descriptions for sample queries in the help
Brodie Rao <brodie@bitheap.org>
parents:
12657
diff
changeset
|
133 |
12808
74f6531581e8
help: use Windows cmd compatible quoting in revset help
Mads Kiilerich <mads@kiilerich.com>
parents:
12716
diff
changeset
|
134 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
|
135 |
5aa5cbaf6efc
revsets: add descriptions for sample queries in the help
Brodie Rao <brodie@bitheap.org>
parents:
12657
diff
changeset
|
136 - 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
|
137 |
12808
74f6531581e8
help: use Windows cmd compatible quoting in revset help
Mads Kiilerich <mads@kiilerich.com>
parents:
12716
diff
changeset
|
138 hg log -r "branch(default) and 1.5:: and not merge()" |
11382 | 139 |
12660
6ed5ae6264c2
revsets: add a sample query to the help for getting active branches
Brodie Rao <brodie@bitheap.org>
parents:
12659
diff
changeset
|
140 - 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
|
141 |
12808
74f6531581e8
help: use Windows cmd compatible quoting in revset help
Mads Kiilerich <mads@kiilerich.com>
parents:
12716
diff
changeset
|
142 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
|
143 |
12659
5aa5cbaf6efc
revsets: add descriptions for sample queries in the help
Brodie Rao <brodie@bitheap.org>
parents:
12657
diff
changeset
|
144 - 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
|
145 ``hgext/*``:: |
12659
5aa5cbaf6efc
revsets: add descriptions for sample queries in the help
Brodie Rao <brodie@bitheap.org>
parents:
12657
diff
changeset
|
146 |
12808
74f6531581e8
help: use Windows cmd compatible quoting in revset help
Mads Kiilerich <mads@kiilerich.com>
parents:
12716
diff
changeset
|
147 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
|
148 |
13937
5f126c01ebfa
help/revset: fix grammar
Idan Kamara <idankk86@gmail.com>
parents:
12821
diff
changeset
|
149 - 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
|
150 |
12808
74f6531581e8
help: use Windows cmd compatible quoting in revset help
Mads Kiilerich <mads@kiilerich.com>
parents:
12716
diff
changeset
|
151 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
|
152 |
5aa5cbaf6efc
revsets: add descriptions for sample queries in the help
Brodie Rao <brodie@bitheap.org>
parents:
12657
diff
changeset
|
153 - 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
|
154 release:: |
5aa5cbaf6efc
revsets: add descriptions for sample queries in the help
Brodie Rao <brodie@bitheap.org>
parents:
12657
diff
changeset
|
155 |
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
|
156 hg log -r "(keyword(bug) or keyword(issue)) and not ancestors(tag())" |