Mercurial > hg
annotate mercurial/help/templates.txt @ 13585:2e80d495592a
templates: generate keyword help dynamically
author | Patrick Mezard <pmezard@gmail.com> |
---|---|
date | Sat, 12 Mar 2011 12:46:31 +0100 |
parents | 6ec84cbcb943 |
children | 264f292a0c6f |
rev | line source |
---|---|
9540
cad36e496640
help: un-indent help topics
Martin Geisler <mg@lazybytes.net>
parents:
9539
diff
changeset
|
1 Mercurial allows you to customize output of commands through |
cad36e496640
help: un-indent help topics
Martin Geisler <mg@lazybytes.net>
parents:
9539
diff
changeset
|
2 templates. You can either pass in a template from the command |
cad36e496640
help: un-indent help topics
Martin Geisler <mg@lazybytes.net>
parents:
9539
diff
changeset
|
3 line, via the --template option, or select an existing |
cad36e496640
help: un-indent help topics
Martin Geisler <mg@lazybytes.net>
parents:
9539
diff
changeset
|
4 template-style (--style). |
9539
c904e76e3834
help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents:
diff
changeset
|
5 |
9540
cad36e496640
help: un-indent help topics
Martin Geisler <mg@lazybytes.net>
parents:
9539
diff
changeset
|
6 You can customize output for any "log-like" command: log, |
cad36e496640
help: un-indent help topics
Martin Geisler <mg@lazybytes.net>
parents:
9539
diff
changeset
|
7 outgoing, incoming, tip, parents, heads and glog. |
9539
c904e76e3834
help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents:
diff
changeset
|
8 |
11034
3b89899934a6
log: document the new xml style
Dan Connolly <http://www.w3.org/People/Connolly/>
parents:
10759
diff
changeset
|
9 Four styles are packaged with Mercurial: default (the style used |
3b89899934a6
log: document the new xml style
Dan Connolly <http://www.w3.org/People/Connolly/>
parents:
10759
diff
changeset
|
10 when no explicit preference is passed), compact, changelog, |
3b89899934a6
log: document the new xml style
Dan Connolly <http://www.w3.org/People/Connolly/>
parents:
10759
diff
changeset
|
11 and xml. |
9540
cad36e496640
help: un-indent help topics
Martin Geisler <mg@lazybytes.net>
parents:
9539
diff
changeset
|
12 Usage:: |
9539
c904e76e3834
help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents:
diff
changeset
|
13 |
9540
cad36e496640
help: un-indent help topics
Martin Geisler <mg@lazybytes.net>
parents:
9539
diff
changeset
|
14 $ hg log -r1 --style changelog |
9539
c904e76e3834
help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents:
diff
changeset
|
15 |
9540
cad36e496640
help: un-indent help topics
Martin Geisler <mg@lazybytes.net>
parents:
9539
diff
changeset
|
16 A template is a piece of text, with markup to invoke variable |
cad36e496640
help: un-indent help topics
Martin Geisler <mg@lazybytes.net>
parents:
9539
diff
changeset
|
17 expansion:: |
9539
c904e76e3834
help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents:
diff
changeset
|
18 |
9540
cad36e496640
help: un-indent help topics
Martin Geisler <mg@lazybytes.net>
parents:
9539
diff
changeset
|
19 $ hg log -r1 --template "{node}\n" |
cad36e496640
help: un-indent help topics
Martin Geisler <mg@lazybytes.net>
parents:
9539
diff
changeset
|
20 b56ce7b07c52de7d5fd79fb89701ea538af65746 |
9539
c904e76e3834
help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents:
diff
changeset
|
21 |
9540
cad36e496640
help: un-indent help topics
Martin Geisler <mg@lazybytes.net>
parents:
9539
diff
changeset
|
22 Strings in curly braces are called keywords. The availability of |
cad36e496640
help: un-indent help topics
Martin Geisler <mg@lazybytes.net>
parents:
9539
diff
changeset
|
23 keywords depends on the exact context of the templater. These |
cad36e496640
help: un-indent help topics
Martin Geisler <mg@lazybytes.net>
parents:
9539
diff
changeset
|
24 keywords are usually available for templating a log-like command: |
9539
c904e76e3834
help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents:
diff
changeset
|
25 |
13585
2e80d495592a
templates: generate keyword help dynamically
Patrick Mezard <pmezard@gmail.com>
parents:
13498
diff
changeset
|
26 .. keywordsmarker |
9539
c904e76e3834
help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents:
diff
changeset
|
27 |
9540
cad36e496640
help: un-indent help topics
Martin Geisler <mg@lazybytes.net>
parents:
9539
diff
changeset
|
28 The "date" keyword does not produce human-readable output. If you |
cad36e496640
help: un-indent help topics
Martin Geisler <mg@lazybytes.net>
parents:
9539
diff
changeset
|
29 want to use a date in your output, you can use a filter to process |
cad36e496640
help: un-indent help topics
Martin Geisler <mg@lazybytes.net>
parents:
9539
diff
changeset
|
30 it. Filters are functions which return a string based on the input |
10759
9f6e30a89f11
help: point out need for stringification
Dirkjan Ochtman <dirkjan@ochtman.nl>
parents:
10066
diff
changeset
|
31 variable. Be sure to use the stringify filter first when you're |
9f6e30a89f11
help: point out need for stringification
Dirkjan Ochtman <dirkjan@ochtman.nl>
parents:
10066
diff
changeset
|
32 applying a string-input filter to a list-like input variable. |
9f6e30a89f11
help: point out need for stringification
Dirkjan Ochtman <dirkjan@ochtman.nl>
parents:
10066
diff
changeset
|
33 You can also use a chain of filters to get the desired output:: |
9539
c904e76e3834
help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents:
diff
changeset
|
34 |
9540
cad36e496640
help: un-indent help topics
Martin Geisler <mg@lazybytes.net>
parents:
9539
diff
changeset
|
35 $ hg tip --template "{date|isodate}\n" |
cad36e496640
help: un-indent help topics
Martin Geisler <mg@lazybytes.net>
parents:
9539
diff
changeset
|
36 2008-08-21 18:22 +0000 |
9539
c904e76e3834
help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents:
diff
changeset
|
37 |
9540
cad36e496640
help: un-indent help topics
Martin Geisler <mg@lazybytes.net>
parents:
9539
diff
changeset
|
38 List of filters: |
9539
c904e76e3834
help: move help topics from mercurial/help.py to help/*.txt
Martin Geisler <mg@lazybytes.net>
parents:
diff
changeset
|
39 |
10066
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
40 :addbreaks: Any text. Add an XHTML "<br />" tag before the end of |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
41 every line except the last. |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
42 |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
43 :age: Date. Returns a human-readable date/time difference between the |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
44 given date/time and the current date/time. |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
45 |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
46 :basename: Any text. Treats the text as a path, and returns the last |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
47 component of the path after splitting by the path separator |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
48 (ignoring trailing separators). For example, "foo/bar/baz" becomes |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
49 "baz" and "foo/bar//" becomes "bar". |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
50 |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
51 :stripdir: Treat the text as path and strip a directory level, if |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
52 possible. For example, "foo" and "foo/bar" becomes "foo". |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
53 |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
54 :date: Date. Returns a date in a Unix date format, including the |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
55 timezone: "Mon Sep 04 15:13:13 2006 0700". |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
56 |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
57 :domain: Any text. Finds the first string that looks like an email |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
58 address, and extracts just the domain component. Example: ``User |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
59 <user@example.com>`` becomes ``example.com``. |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
60 |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
61 :email: Any text. Extracts the first string that looks like an email |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
62 address. Example: ``User <user@example.com>`` becomes |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
63 ``user@example.com``. |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
64 |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
65 :escape: Any text. Replaces the special XML/XHTML characters "&", "<" |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
66 and ">" with XML entities. |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
67 |
12371
48a4acd1ccf1
templater: add hex filter.
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents:
11970
diff
changeset
|
68 :hex: Any text. Convert a binary Mercurial node identifier into |
48a4acd1ccf1
templater: add hex filter.
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents:
11970
diff
changeset
|
69 its long hexadecimal representation. |
48a4acd1ccf1
templater: add hex filter.
Dan Villiom Podlaski Christiansen <danchr@gmail.com>
parents:
11970
diff
changeset
|
70 |
10066
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
71 :fill68: Any text. Wraps the text to fit in 68 columns. |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
72 |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
73 :fill76: Any text. Wraps the text to fit in 76 columns. |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
74 |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
75 :firstline: Any text. Returns the first line of text. |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
76 |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
77 :nonempty: Any text. Returns '(none)' if the string is empty. |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
78 |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
79 :hgdate: Date. Returns the date as a pair of numbers: "1157407993 |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
80 25200" (Unix timestamp, timezone offset). |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
81 |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
82 :isodate: Date. Returns the date in ISO 8601 format: "2009-08-18 13:00 |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
83 +0200". |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
84 |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
85 :isodatesec: Date. Returns the date in ISO 8601 format, including |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
86 seconds: "2009-08-18 13:00:13 +0200". See also the rfc3339date |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
87 filter. |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
88 |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
89 :localdate: Date. Converts a date to local date. |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
90 |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
91 :obfuscate: Any text. Returns the input text rendered as a sequence of |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
92 XML entities. |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
93 |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
94 :person: Any text. Returns the text before an email address. |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
95 |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
96 :rfc822date: Date. Returns a date using the same format used in email |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
97 headers: "Tue, 18 Aug 2009 13:00:13 +0200". |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
98 |
9540
cad36e496640
help: un-indent help topics
Martin Geisler <mg@lazybytes.net>
parents:
9539
diff
changeset
|
99 :rfc3339date: Date. Returns a date using the Internet date format |
10066
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
100 specified in RFC 3339: "2009-08-18T13:00:13+02:00". |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
101 |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
102 :short: Changeset hash. Returns the short form of a changeset hash, |
11718
3e979f47a4c9
help: fix bytes/digit confusion for hashes
Matt Mackall <mpm@selenic.com>
parents:
11655
diff
changeset
|
103 i.e. a 12 hexadecimal digit string. |
10066
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
104 |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
105 :shortdate: Date. Returns a date like "2006-09-18". |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
106 |
11960
df95b31bbdd7
help: document stringify templatefilter
Dirkjan Ochtman <dirkjan@ochtman.nl>
parents:
11034
diff
changeset
|
107 :stringify: Any type. Turns the value into text by converting values into |
df95b31bbdd7
help: document stringify templatefilter
Dirkjan Ochtman <dirkjan@ochtman.nl>
parents:
11034
diff
changeset
|
108 text and concatenating them. |
df95b31bbdd7
help: document stringify templatefilter
Dirkjan Ochtman <dirkjan@ochtman.nl>
parents:
11034
diff
changeset
|
109 |
10066
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
110 :strip: Any text. Strips all leading and trailing whitespace. |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
111 |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
112 :tabindent: Any text. Returns the text, with every line except the |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
113 first starting with a tab character. |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
114 |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
115 :urlescape: Any text. Escapes all "special" characters. For example, |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
116 "foo bar" becomes "foo%20bar". |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
117 |
788e7d04c594
help/templates: use hanging indent for field list
Martin Geisler <mg@lazybytes.net>
parents:
10061
diff
changeset
|
118 :user: Any text. Returns the user portion of an email address. |