##// END OF EJS Templates
help: document isodatesec and rfc3339 filters (issue1799)
Martin Geisler -
r9359:9bf49b37 default
parent child Browse files
Show More
@@ -1,510 +1,514 b''
1 # help.py - help data for mercurial
1 # help.py - help data for mercurial
2 #
2 #
3 # Copyright 2006 Matt Mackall <mpm@selenic.com>
3 # Copyright 2006 Matt Mackall <mpm@selenic.com>
4 #
4 #
5 # This software may be used and distributed according to the terms of the
5 # This software may be used and distributed according to the terms of the
6 # GNU General Public License version 2, incorporated herein by reference.
6 # GNU General Public License version 2, incorporated herein by reference.
7
7
8 from i18n import _
8 from i18n import _
9 import extensions, util
9 import extensions, util
10
10
11
11
12 def moduledoc(file):
12 def moduledoc(file):
13 '''return the top-level python documentation for the given file
13 '''return the top-level python documentation for the given file
14
14
15 Loosely inspired by pydoc.source_synopsis(), but rewritten to handle \'''
15 Loosely inspired by pydoc.source_synopsis(), but rewritten to handle \'''
16 as well as """ and to return the whole text instead of just the synopsis'''
16 as well as """ and to return the whole text instead of just the synopsis'''
17 result = []
17 result = []
18
18
19 line = file.readline()
19 line = file.readline()
20 while line[:1] == '#' or not line.strip():
20 while line[:1] == '#' or not line.strip():
21 line = file.readline()
21 line = file.readline()
22 if not line: break
22 if not line: break
23
23
24 start = line[:3]
24 start = line[:3]
25 if start == '"""' or start == "'''":
25 if start == '"""' or start == "'''":
26 line = line[3:]
26 line = line[3:]
27 while line:
27 while line:
28 if line.rstrip().endswith(start):
28 if line.rstrip().endswith(start):
29 line = line.split(start)[0]
29 line = line.split(start)[0]
30 if line:
30 if line:
31 result.append(line)
31 result.append(line)
32 break
32 break
33 elif not line:
33 elif not line:
34 return None # unmatched delimiter
34 return None # unmatched delimiter
35 result.append(line)
35 result.append(line)
36 line = file.readline()
36 line = file.readline()
37 else:
37 else:
38 return None
38 return None
39
39
40 return ''.join(result)
40 return ''.join(result)
41
41
42 def listexts(header, exts, maxlength):
42 def listexts(header, exts, maxlength):
43 '''return a text listing of the given extensions'''
43 '''return a text listing of the given extensions'''
44 if not exts:
44 if not exts:
45 return ''
45 return ''
46 result = '\n%s\n\n' % header
46 result = '\n%s\n\n' % header
47 for name, desc in sorted(exts.iteritems()):
47 for name, desc in sorted(exts.iteritems()):
48 desc = util.wrap(desc, maxlength + 4)
48 desc = util.wrap(desc, maxlength + 4)
49 result += ' %s %s\n' % (name.ljust(maxlength), desc)
49 result += ' %s %s\n' % (name.ljust(maxlength), desc)
50 return result
50 return result
51
51
52 def extshelp():
52 def extshelp():
53 doc = _(r'''
53 doc = _(r'''
54 Mercurial has the ability to add new features through the use of
54 Mercurial has the ability to add new features through the use of
55 extensions. Extensions may add new commands, add options to
55 extensions. Extensions may add new commands, add options to
56 existing commands, change the default behavior of commands, or
56 existing commands, change the default behavior of commands, or
57 implement hooks.
57 implement hooks.
58
58
59 Extensions are not loaded by default for a variety of reasons:
59 Extensions are not loaded by default for a variety of reasons:
60 they can increase startup overhead; they may be meant for
60 they can increase startup overhead; they may be meant for
61 advanced usage only; they may provide potentially dangerous
61 advanced usage only; they may provide potentially dangerous
62 abilities (such as letting you destroy or modify history); they
62 abilities (such as letting you destroy or modify history); they
63 might not be ready for prime time; or they may alter some
63 might not be ready for prime time; or they may alter some
64 usual behaviors of stock Mercurial. It is thus up to the user to
64 usual behaviors of stock Mercurial. It is thus up to the user to
65 activate extensions as needed.
65 activate extensions as needed.
66
66
67 To enable the "foo" extension, either shipped with Mercurial
67 To enable the "foo" extension, either shipped with Mercurial
68 or in the Python search path, create an entry for it in your
68 or in the Python search path, create an entry for it in your
69 hgrc, like this:
69 hgrc, like this:
70
70
71 [extensions]
71 [extensions]
72 foo =
72 foo =
73
73
74 You may also specify the full path to an extension:
74 You may also specify the full path to an extension:
75
75
76 [extensions]
76 [extensions]
77 myfeature = ~/.hgext/myfeature.py
77 myfeature = ~/.hgext/myfeature.py
78
78
79 To explicitly disable an extension enabled in an hgrc of broader
79 To explicitly disable an extension enabled in an hgrc of broader
80 scope, prepend its path with !:
80 scope, prepend its path with !:
81
81
82 [extensions]
82 [extensions]
83 # disabling extension bar residing in /path/to/extension/bar.py
83 # disabling extension bar residing in /path/to/extension/bar.py
84 hgext.bar = !/path/to/extension/bar.py
84 hgext.bar = !/path/to/extension/bar.py
85 # ditto, but no path was supplied for extension baz
85 # ditto, but no path was supplied for extension baz
86 hgext.baz = !
86 hgext.baz = !
87 ''')
87 ''')
88
88
89 exts, maxlength = extensions.enabled()
89 exts, maxlength = extensions.enabled()
90 doc += listexts(_('enabled extensions:'), exts, maxlength)
90 doc += listexts(_('enabled extensions:'), exts, maxlength)
91
91
92 exts, maxlength = extensions.disabled()
92 exts, maxlength = extensions.disabled()
93 doc += listexts(_('disabled extensions:'), exts, maxlength)
93 doc += listexts(_('disabled extensions:'), exts, maxlength)
94
94
95 return doc
95 return doc
96
96
97 helptable = (
97 helptable = (
98 (["dates"], _("Date Formats"),
98 (["dates"], _("Date Formats"),
99 _(r'''
99 _(r'''
100 Some commands allow the user to specify a date, e.g.:
100 Some commands allow the user to specify a date, e.g.:
101 * backout, commit, import, tag: Specify the commit date.
101 * backout, commit, import, tag: Specify the commit date.
102 * log, revert, update: Select revision(s) by date.
102 * log, revert, update: Select revision(s) by date.
103
103
104 Many date formats are valid. Here are some examples:
104 Many date formats are valid. Here are some examples:
105
105
106 "Wed Dec 6 13:18:29 2006" (local timezone assumed)
106 "Wed Dec 6 13:18:29 2006" (local timezone assumed)
107 "Dec 6 13:18 -0600" (year assumed, time offset provided)
107 "Dec 6 13:18 -0600" (year assumed, time offset provided)
108 "Dec 6 13:18 UTC" (UTC and GMT are aliases for +0000)
108 "Dec 6 13:18 UTC" (UTC and GMT are aliases for +0000)
109 "Dec 6" (midnight)
109 "Dec 6" (midnight)
110 "13:18" (today assumed)
110 "13:18" (today assumed)
111 "3:39" (3:39AM assumed)
111 "3:39" (3:39AM assumed)
112 "3:39pm" (15:39)
112 "3:39pm" (15:39)
113 "2006-12-06 13:18:29" (ISO 8601 format)
113 "2006-12-06 13:18:29" (ISO 8601 format)
114 "2006-12-6 13:18"
114 "2006-12-6 13:18"
115 "2006-12-6"
115 "2006-12-6"
116 "12-6"
116 "12-6"
117 "12/6"
117 "12/6"
118 "12/6/6" (Dec 6 2006)
118 "12/6/6" (Dec 6 2006)
119
119
120 Lastly, there is Mercurial's internal format:
120 Lastly, there is Mercurial's internal format:
121
121
122 "1165432709 0" (Wed Dec 6 13:18:29 2006 UTC)
122 "1165432709 0" (Wed Dec 6 13:18:29 2006 UTC)
123
123
124 This is the internal representation format for dates. unixtime is
124 This is the internal representation format for dates. unixtime is
125 the number of seconds since the epoch (1970-01-01 00:00 UTC).
125 the number of seconds since the epoch (1970-01-01 00:00 UTC).
126 offset is the offset of the local timezone, in seconds west of UTC
126 offset is the offset of the local timezone, in seconds west of UTC
127 (negative if the timezone is east of UTC).
127 (negative if the timezone is east of UTC).
128
128
129 The log command also accepts date ranges:
129 The log command also accepts date ranges:
130
130
131 "<{datetime}" - at or before a given date/time
131 "<{datetime}" - at or before a given date/time
132 ">{datetime}" - on or after a given date/time
132 ">{datetime}" - on or after a given date/time
133 "{datetime} to {datetime}" - a date range, inclusive
133 "{datetime} to {datetime}" - a date range, inclusive
134 "-{days}" - within a given number of days of today
134 "-{days}" - within a given number of days of today
135 ''')),
135 ''')),
136
136
137 (["patterns"], _("File Name Patterns"),
137 (["patterns"], _("File Name Patterns"),
138 _(r'''
138 _(r'''
139 Mercurial accepts several notations for identifying one or more
139 Mercurial accepts several notations for identifying one or more
140 files at a time.
140 files at a time.
141
141
142 By default, Mercurial treats filenames as shell-style extended
142 By default, Mercurial treats filenames as shell-style extended
143 glob patterns.
143 glob patterns.
144
144
145 Alternate pattern notations must be specified explicitly.
145 Alternate pattern notations must be specified explicitly.
146
146
147 To use a plain path name without any pattern matching, start it
147 To use a plain path name without any pattern matching, start it
148 with "path:". These path names must completely match starting at
148 with "path:". These path names must completely match starting at
149 the current repository root.
149 the current repository root.
150
150
151 To use an extended glob, start a name with "glob:". Globs are
151 To use an extended glob, start a name with "glob:". Globs are
152 rooted at the current directory; a glob such as "*.c" will only
152 rooted at the current directory; a glob such as "*.c" will only
153 match files in the current directory ending with ".c".
153 match files in the current directory ending with ".c".
154
154
155 The supported glob syntax extensions are "**" to match any string
155 The supported glob syntax extensions are "**" to match any string
156 across path separators and "{a,b}" to mean "a or b".
156 across path separators and "{a,b}" to mean "a or b".
157
157
158 To use a Perl/Python regular expression, start a name with "re:".
158 To use a Perl/Python regular expression, start a name with "re:".
159 Regexp pattern matching is anchored at the root of the repository.
159 Regexp pattern matching is anchored at the root of the repository.
160
160
161 Plain examples:
161 Plain examples:
162
162
163 path:foo/bar a name bar in a directory named foo in the root of
163 path:foo/bar a name bar in a directory named foo in the root of
164 the repository
164 the repository
165 path:path:name a file or directory named "path:name"
165 path:path:name a file or directory named "path:name"
166
166
167 Glob examples:
167 Glob examples:
168
168
169 glob:*.c any name ending in ".c" in the current directory
169 glob:*.c any name ending in ".c" in the current directory
170 *.c any name ending in ".c" in the current directory
170 *.c any name ending in ".c" in the current directory
171 **.c any name ending in ".c" in any subdirectory of the
171 **.c any name ending in ".c" in any subdirectory of the
172 current directory including itself.
172 current directory including itself.
173 foo/*.c any name ending in ".c" in the directory foo
173 foo/*.c any name ending in ".c" in the directory foo
174 foo/**.c any name ending in ".c" in any subdirectory of foo
174 foo/**.c any name ending in ".c" in any subdirectory of foo
175 including itself.
175 including itself.
176
176
177 Regexp examples:
177 Regexp examples:
178
178
179 re:.*\.c$ any name ending in ".c", anywhere in the repository
179 re:.*\.c$ any name ending in ".c", anywhere in the repository
180
180
181 ''')),
181 ''')),
182
182
183 (['environment', 'env'], _('Environment Variables'),
183 (['environment', 'env'], _('Environment Variables'),
184 _(r'''
184 _(r'''
185 HG::
185 HG::
186 Path to the 'hg' executable, automatically passed when running
186 Path to the 'hg' executable, automatically passed when running
187 hooks, extensions or external tools. If unset or empty, this is
187 hooks, extensions or external tools. If unset or empty, this is
188 the hg executable's name if it's frozen, or an executable named
188 the hg executable's name if it's frozen, or an executable named
189 'hg' (with %PATHEXT% [defaulting to COM/EXE/BAT/CMD] extensions on
189 'hg' (with %PATHEXT% [defaulting to COM/EXE/BAT/CMD] extensions on
190 Windows) is searched.
190 Windows) is searched.
191
191
192 HGEDITOR::
192 HGEDITOR::
193 This is the name of the editor to run when committing. See EDITOR.
193 This is the name of the editor to run when committing. See EDITOR.
194
194
195 (deprecated, use .hgrc)
195 (deprecated, use .hgrc)
196
196
197 HGENCODING::
197 HGENCODING::
198 This overrides the default locale setting detected by Mercurial.
198 This overrides the default locale setting detected by Mercurial.
199 This setting is used to convert data including usernames,
199 This setting is used to convert data including usernames,
200 changeset descriptions, tag names, and branches. This setting can
200 changeset descriptions, tag names, and branches. This setting can
201 be overridden with the --encoding command-line option.
201 be overridden with the --encoding command-line option.
202
202
203 HGENCODINGMODE::
203 HGENCODINGMODE::
204 This sets Mercurial's behavior for handling unknown characters
204 This sets Mercurial's behavior for handling unknown characters
205 while transcoding user input. The default is "strict", which
205 while transcoding user input. The default is "strict", which
206 causes Mercurial to abort if it can't map a character. Other
206 causes Mercurial to abort if it can't map a character. Other
207 settings include "replace", which replaces unknown characters, and
207 settings include "replace", which replaces unknown characters, and
208 "ignore", which drops them. This setting can be overridden with
208 "ignore", which drops them. This setting can be overridden with
209 the --encodingmode command-line option.
209 the --encodingmode command-line option.
210
210
211 HGMERGE::
211 HGMERGE::
212 An executable to use for resolving merge conflicts. The program
212 An executable to use for resolving merge conflicts. The program
213 will be executed with three arguments: local file, remote file,
213 will be executed with three arguments: local file, remote file,
214 ancestor file.
214 ancestor file.
215
215
216 (deprecated, use .hgrc)
216 (deprecated, use .hgrc)
217
217
218 HGRCPATH::
218 HGRCPATH::
219 A list of files or directories to search for hgrc files. Item
219 A list of files or directories to search for hgrc files. Item
220 separator is ":" on Unix, ";" on Windows. If HGRCPATH is not set,
220 separator is ":" on Unix, ";" on Windows. If HGRCPATH is not set,
221 platform default search path is used. If empty, only the .hg/hgrc
221 platform default search path is used. If empty, only the .hg/hgrc
222 from the current repository is read.
222 from the current repository is read.
223
223
224 For each element in HGRCPATH:
224 For each element in HGRCPATH:
225 * if it's a directory, all files ending with .rc are added
225 * if it's a directory, all files ending with .rc are added
226 * otherwise, the file itself will be added
226 * otherwise, the file itself will be added
227
227
228 HGUSER::
228 HGUSER::
229 This is the string used as the author of a commit. If not set,
229 This is the string used as the author of a commit. If not set,
230 available values will be considered in this order:
230 available values will be considered in this order:
231
231
232 * HGUSER (deprecated)
232 * HGUSER (deprecated)
233 * hgrc files from the HGRCPATH
233 * hgrc files from the HGRCPATH
234 * EMAIL
234 * EMAIL
235 * interactive prompt
235 * interactive prompt
236 * LOGNAME (with '@hostname' appended)
236 * LOGNAME (with '@hostname' appended)
237
237
238 (deprecated, use .hgrc)
238 (deprecated, use .hgrc)
239
239
240 EMAIL::
240 EMAIL::
241 May be used as the author of a commit; see HGUSER.
241 May be used as the author of a commit; see HGUSER.
242
242
243 LOGNAME::
243 LOGNAME::
244 May be used as the author of a commit; see HGUSER.
244 May be used as the author of a commit; see HGUSER.
245
245
246 VISUAL::
246 VISUAL::
247 This is the name of the editor to use when committing. See EDITOR.
247 This is the name of the editor to use when committing. See EDITOR.
248
248
249 EDITOR::
249 EDITOR::
250 Sometimes Mercurial needs to open a text file in an editor for a
250 Sometimes Mercurial needs to open a text file in an editor for a
251 user to modify, for example when writing commit messages. The
251 user to modify, for example when writing commit messages. The
252 editor it uses is determined by looking at the environment
252 editor it uses is determined by looking at the environment
253 variables HGEDITOR, VISUAL and EDITOR, in that order. The first
253 variables HGEDITOR, VISUAL and EDITOR, in that order. The first
254 non-empty one is chosen. If all of them are empty, the editor
254 non-empty one is chosen. If all of them are empty, the editor
255 defaults to 'vi'.
255 defaults to 'vi'.
256
256
257 PYTHONPATH::
257 PYTHONPATH::
258 This is used by Python to find imported modules and may need to be
258 This is used by Python to find imported modules and may need to be
259 set appropriately if this Mercurial is not installed system-wide.
259 set appropriately if this Mercurial is not installed system-wide.
260 ''')),
260 ''')),
261
261
262 (['revs', 'revisions'], _('Specifying Single Revisions'),
262 (['revs', 'revisions'], _('Specifying Single Revisions'),
263 _(r'''
263 _(r'''
264 Mercurial supports several ways to specify individual revisions.
264 Mercurial supports several ways to specify individual revisions.
265
265
266 A plain integer is treated as a revision number. Negative integers
266 A plain integer is treated as a revision number. Negative integers
267 are treated as sequential offsets from the tip, with -1 denoting
267 are treated as sequential offsets from the tip, with -1 denoting
268 the tip, -2 denoting the revision prior to the tip, and so forth.
268 the tip, -2 denoting the revision prior to the tip, and so forth.
269
269
270 A 40-digit hexadecimal string is treated as a unique revision
270 A 40-digit hexadecimal string is treated as a unique revision
271 identifier.
271 identifier.
272
272
273 A hexadecimal string less than 40 characters long is treated as a
273 A hexadecimal string less than 40 characters long is treated as a
274 unique revision identifier and is referred to as a short-form
274 unique revision identifier and is referred to as a short-form
275 identifier. A short-form identifier is only valid if it is the
275 identifier. A short-form identifier is only valid if it is the
276 prefix of exactly one full-length identifier.
276 prefix of exactly one full-length identifier.
277
277
278 Any other string is treated as a tag or branch name. A tag name is
278 Any other string is treated as a tag or branch name. A tag name is
279 a symbolic name associated with a revision identifier. A branch
279 a symbolic name associated with a revision identifier. A branch
280 name denotes the tipmost revision of that branch. Tag and branch
280 name denotes the tipmost revision of that branch. Tag and branch
281 names must not contain the ":" character.
281 names must not contain the ":" character.
282
282
283 The reserved name "tip" is a special tag that always identifies
283 The reserved name "tip" is a special tag that always identifies
284 the most recent revision.
284 the most recent revision.
285
285
286 The reserved name "null" indicates the null revision. This is the
286 The reserved name "null" indicates the null revision. This is the
287 revision of an empty repository, and the parent of revision 0.
287 revision of an empty repository, and the parent of revision 0.
288
288
289 The reserved name "." indicates the working directory parent. If
289 The reserved name "." indicates the working directory parent. If
290 no working directory is checked out, it is equivalent to null. If
290 no working directory is checked out, it is equivalent to null. If
291 an uncommitted merge is in progress, "." is the revision of the
291 an uncommitted merge is in progress, "." is the revision of the
292 first parent.
292 first parent.
293 ''')),
293 ''')),
294
294
295 (['mrevs', 'multirevs'], _('Specifying Multiple Revisions'),
295 (['mrevs', 'multirevs'], _('Specifying Multiple Revisions'),
296 _(r'''
296 _(r'''
297 When Mercurial accepts more than one revision, they may be
297 When Mercurial accepts more than one revision, they may be
298 specified individually, or provided as a topologically continuous
298 specified individually, or provided as a topologically continuous
299 range, separated by the ":" character.
299 range, separated by the ":" character.
300
300
301 The syntax of range notation is [BEGIN]:[END], where BEGIN and END
301 The syntax of range notation is [BEGIN]:[END], where BEGIN and END
302 are revision identifiers. Both BEGIN and END are optional. If
302 are revision identifiers. Both BEGIN and END are optional. If
303 BEGIN is not specified, it defaults to revision number 0. If END
303 BEGIN is not specified, it defaults to revision number 0. If END
304 is not specified, it defaults to the tip. The range ":" thus means
304 is not specified, it defaults to the tip. The range ":" thus means
305 "all revisions".
305 "all revisions".
306
306
307 If BEGIN is greater than END, revisions are treated in reverse
307 If BEGIN is greater than END, revisions are treated in reverse
308 order.
308 order.
309
309
310 A range acts as a closed interval. This means that a range of 3:5
310 A range acts as a closed interval. This means that a range of 3:5
311 gives 3, 4 and 5. Similarly, a range of 9:6 gives 9, 8, 7, and 6.
311 gives 3, 4 and 5. Similarly, a range of 9:6 gives 9, 8, 7, and 6.
312 ''')),
312 ''')),
313
313
314 (['diffs'], _('Diff Formats'),
314 (['diffs'], _('Diff Formats'),
315 _(r'''
315 _(r'''
316 Mercurial's default format for showing changes between two
316 Mercurial's default format for showing changes between two
317 versions of a file is compatible with the unified format of GNU
317 versions of a file is compatible with the unified format of GNU
318 diff, which can be used by GNU patch and many other standard
318 diff, which can be used by GNU patch and many other standard
319 tools.
319 tools.
320
320
321 While this standard format is often enough, it does not encode the
321 While this standard format is often enough, it does not encode the
322 following information:
322 following information:
323
323
324 - executable status and other permission bits
324 - executable status and other permission bits
325 - copy or rename information
325 - copy or rename information
326 - changes in binary files
326 - changes in binary files
327 - creation or deletion of empty files
327 - creation or deletion of empty files
328
328
329 Mercurial also supports the extended diff format from the git VCS
329 Mercurial also supports the extended diff format from the git VCS
330 which addresses these limitations. The git diff format is not
330 which addresses these limitations. The git diff format is not
331 produced by default because a few widespread tools still do not
331 produced by default because a few widespread tools still do not
332 understand this format.
332 understand this format.
333
333
334 This means that when generating diffs from a Mercurial repository
334 This means that when generating diffs from a Mercurial repository
335 (e.g. with "hg export"), you should be careful about things like
335 (e.g. with "hg export"), you should be careful about things like
336 file copies and renames or other things mentioned above, because
336 file copies and renames or other things mentioned above, because
337 when applying a standard diff to a different repository, this
337 when applying a standard diff to a different repository, this
338 extra information is lost. Mercurial's internal operations (like
338 extra information is lost. Mercurial's internal operations (like
339 push and pull) are not affected by this, because they use an
339 push and pull) are not affected by this, because they use an
340 internal binary format for communicating changes.
340 internal binary format for communicating changes.
341
341
342 To make Mercurial produce the git extended diff format, use the
342 To make Mercurial produce the git extended diff format, use the
343 --git option available for many commands, or set 'git = True' in
343 --git option available for many commands, or set 'git = True' in
344 the [diff] section of your hgrc. You do not need to set this
344 the [diff] section of your hgrc. You do not need to set this
345 option when importing diffs in this format or using them in the mq
345 option when importing diffs in this format or using them in the mq
346 extension.
346 extension.
347 ''')),
347 ''')),
348 (['templating'], _('Template Usage'),
348 (['templating'], _('Template Usage'),
349 _(r'''
349 _(r'''
350 Mercurial allows you to customize output of commands through
350 Mercurial allows you to customize output of commands through
351 templates. You can either pass in a template from the command
351 templates. You can either pass in a template from the command
352 line, via the --template option, or select an existing
352 line, via the --template option, or select an existing
353 template-style (--style).
353 template-style (--style).
354
354
355 You can customize output for any "log-like" command: log,
355 You can customize output for any "log-like" command: log,
356 outgoing, incoming, tip, parents, heads and glog.
356 outgoing, incoming, tip, parents, heads and glog.
357
357
358 Three styles are packaged with Mercurial: default (the style used
358 Three styles are packaged with Mercurial: default (the style used
359 when no explicit preference is passed), compact and changelog.
359 when no explicit preference is passed), compact and changelog.
360 Usage:
360 Usage:
361
361
362 $ hg log -r1 --style changelog
362 $ hg log -r1 --style changelog
363
363
364 A template is a piece of text, with markup to invoke variable
364 A template is a piece of text, with markup to invoke variable
365 expansion:
365 expansion:
366
366
367 $ hg log -r1 --template "{node}\n"
367 $ hg log -r1 --template "{node}\n"
368 b56ce7b07c52de7d5fd79fb89701ea538af65746
368 b56ce7b07c52de7d5fd79fb89701ea538af65746
369
369
370 Strings in curly braces are called keywords. The availability of
370 Strings in curly braces are called keywords. The availability of
371 keywords depends on the exact context of the templater. These
371 keywords depends on the exact context of the templater. These
372 keywords are usually available for templating a log-like command:
372 keywords are usually available for templating a log-like command:
373
373
374 - author: String. The unmodified author of the changeset.
374 - author: String. The unmodified author of the changeset.
375 - branches: String. The name of the branch on which the changeset
375 - branches: String. The name of the branch on which the changeset
376 was committed. Will be empty if the branch name was default.
376 was committed. Will be empty if the branch name was default.
377 - date: Date information. The date when the changeset was committed.
377 - date: Date information. The date when the changeset was committed.
378 - desc: String. The text of the changeset description.
378 - desc: String. The text of the changeset description.
379 - diffstat: String. Statistics of changes with the following
379 - diffstat: String. Statistics of changes with the following
380 format: "modified files: +added/-removed lines"
380 format: "modified files: +added/-removed lines"
381 - files: List of strings. All files modified, added, or removed by
381 - files: List of strings. All files modified, added, or removed by
382 this changeset.
382 this changeset.
383 - file_adds: List of strings. Files added by this changeset.
383 - file_adds: List of strings. Files added by this changeset.
384 - file_mods: List of strings. Files modified by this changeset.
384 - file_mods: List of strings. Files modified by this changeset.
385 - file_dels: List of strings. Files removed by this changeset.
385 - file_dels: List of strings. Files removed by this changeset.
386 - node: String. The changeset identification hash, as a
386 - node: String. The changeset identification hash, as a
387 40-character hexadecimal string.
387 40-character hexadecimal string.
388 - parents: List of strings. The parents of the changeset.
388 - parents: List of strings. The parents of the changeset.
389 - rev: Integer. The repository-local changeset revision number.
389 - rev: Integer. The repository-local changeset revision number.
390 - tags: List of strings. Any tags associated with the changeset.
390 - tags: List of strings. Any tags associated with the changeset.
391
391
392 The "date" keyword does not produce human-readable output. If you
392 The "date" keyword does not produce human-readable output. If you
393 want to use a date in your output, you can use a filter to process
393 want to use a date in your output, you can use a filter to process
394 it. Filters are functions which return a string based on the input
394 it. Filters are functions which return a string based on the input
395 variable. You can also use a chain of filters to get the desired
395 variable. You can also use a chain of filters to get the desired
396 output:
396 output:
397
397
398 $ hg tip --template "{date|isodate}\n"
398 $ hg tip --template "{date|isodate}\n"
399 2008-08-21 18:22 +0000
399 2008-08-21 18:22 +0000
400
400
401 List of filters:
401 List of filters:
402
402
403 - addbreaks: Any text. Add an XHTML "<br />" tag before the end of
403 - addbreaks: Any text. Add an XHTML "<br />" tag before the end of
404 every line except the last.
404 every line except the last.
405 - age: Date. Returns a human-readable date/time difference between
405 - age: Date. Returns a human-readable date/time difference between
406 the given date/time and the current date/time.
406 the given date/time and the current date/time.
407 - basename: Any text. Treats the text as a path, and returns the
407 - basename: Any text. Treats the text as a path, and returns the
408 last component of the path after splitting by the path
408 last component of the path after splitting by the path
409 separator (ignoring trailing separators). For example,
409 separator (ignoring trailing separators). For example,
410 "foo/bar/baz" becomes "baz" and "foo/bar//" becomes "bar".
410 "foo/bar/baz" becomes "baz" and "foo/bar//" becomes "bar".
411 - stripdir: Treat the text as path and strip a directory level, if
411 - stripdir: Treat the text as path and strip a directory level, if
412 possible. For example, "foo" and "foo/bar" becomes "foo".
412 possible. For example, "foo" and "foo/bar" becomes "foo".
413 - date: Date. Returns a date in a Unix date format, including
413 - date: Date. Returns a date in a Unix date format, including
414 the timezone: "Mon Sep 04 15:13:13 2006 0700".
414 the timezone: "Mon Sep 04 15:13:13 2006 0700".
415 - domain: Any text. Finds the first string that looks like an
415 - domain: Any text. Finds the first string that looks like an
416 email address, and extracts just the domain component.
416 email address, and extracts just the domain component.
417 Example: 'User <user@example.com>' becomes 'example.com'.
417 Example: 'User <user@example.com>' becomes 'example.com'.
418 - email: Any text. Extracts the first string that looks like an
418 - email: Any text. Extracts the first string that looks like an
419 email address. Example: 'User <user@example.com>' becomes
419 email address. Example: 'User <user@example.com>' becomes
420 'user@example.com'.
420 'user@example.com'.
421 - escape: Any text. Replaces the special XML/XHTML characters "&",
421 - escape: Any text. Replaces the special XML/XHTML characters "&",
422 "<" and ">" with XML entities.
422 "<" and ">" with XML entities.
423 - fill68: Any text. Wraps the text to fit in 68 columns.
423 - fill68: Any text. Wraps the text to fit in 68 columns.
424 - fill76: Any text. Wraps the text to fit in 76 columns.
424 - fill76: Any text. Wraps the text to fit in 76 columns.
425 - firstline: Any text. Returns the first line of text.
425 - firstline: Any text. Returns the first line of text.
426 - nonempty: Any text. Returns '(none)' if the string is empty.
426 - nonempty: Any text. Returns '(none)' if the string is empty.
427 - hgdate: Date. Returns the date as a pair of numbers:
427 - hgdate: Date. Returns the date as a pair of numbers:
428 "1157407993 25200" (Unix timestamp, timezone offset).
428 "1157407993 25200" (Unix timestamp, timezone offset).
429 - isodate: Date. Returns the date in ISO 8601 format.
429 - isodate: Date. Returns the date in ISO 8601 format.
430 - isodatesec: Date. Returns the date in ISO 8601 format, including
431 seconds. See also the rfc3339date filter.
430 - localdate: Date. Converts a date to local date.
432 - localdate: Date. Converts a date to local date.
431 - obfuscate: Any text. Returns the input text rendered as a
433 - obfuscate: Any text. Returns the input text rendered as a
432 sequence of XML entities.
434 sequence of XML entities.
433 - person: Any text. Returns the text before an email address.
435 - person: Any text. Returns the text before an email address.
434 - rfc822date: Date. Returns a date using the same format used
436 - rfc822date: Date. Returns a date using the same format used
435 in email headers.
437 in email headers.
438 - rfc3339date: Date. Returns a date using the Internet date format
439 specified in RFC 3339.
436 - short: Changeset hash. Returns the short form of a changeset
440 - short: Changeset hash. Returns the short form of a changeset
437 hash, i.e. a 12-byte hexadecimal string.
441 hash, i.e. a 12-byte hexadecimal string.
438 - shortdate: Date. Returns a date like "2006-09-18".
442 - shortdate: Date. Returns a date like "2006-09-18".
439 - strip: Any text. Strips all leading and trailing whitespace.
443 - strip: Any text. Strips all leading and trailing whitespace.
440 - tabindent: Any text. Returns the text, with every line except
444 - tabindent: Any text. Returns the text, with every line except
441 the first starting with a tab character.
445 the first starting with a tab character.
442 - urlescape: Any text. Escapes all "special" characters. For
446 - urlescape: Any text. Escapes all "special" characters. For
443 example, "foo bar" becomes "foo%20bar".
447 example, "foo bar" becomes "foo%20bar".
444 - user: Any text. Returns the user portion of an email address.
448 - user: Any text. Returns the user portion of an email address.
445 ''')),
449 ''')),
446
450
447 (['urls'], _('URL Paths'),
451 (['urls'], _('URL Paths'),
448 _(r'''
452 _(r'''
449 Valid URLs are of the form:
453 Valid URLs are of the form:
450
454
451 local/filesystem/path[#revision]
455 local/filesystem/path[#revision]
452 file://local/filesystem/path[#revision]
456 file://local/filesystem/path[#revision]
453 http://[user[:pass]@]host[:port]/[path][#revision]
457 http://[user[:pass]@]host[:port]/[path][#revision]
454 https://[user[:pass]@]host[:port]/[path][#revision]
458 https://[user[:pass]@]host[:port]/[path][#revision]
455 ssh://[user[:pass]@]host[:port]/[path][#revision]
459 ssh://[user[:pass]@]host[:port]/[path][#revision]
456
460
457 Paths in the local filesystem can either point to Mercurial
461 Paths in the local filesystem can either point to Mercurial
458 repositories or to bundle files (as created by 'hg bundle' or
462 repositories or to bundle files (as created by 'hg bundle' or
459 'hg incoming --bundle').
463 'hg incoming --bundle').
460
464
461 An optional identifier after # indicates a particular branch, tag,
465 An optional identifier after # indicates a particular branch, tag,
462 or changeset to use from the remote repository. See also 'hg help
466 or changeset to use from the remote repository. See also 'hg help
463 revisions'.
467 revisions'.
464
468
465 Some features, such as pushing to http:// and https:// URLs are
469 Some features, such as pushing to http:// and https:// URLs are
466 only possible if the feature is explicitly enabled on the remote
470 only possible if the feature is explicitly enabled on the remote
467 Mercurial server.
471 Mercurial server.
468
472
469 Some notes about using SSH with Mercurial:
473 Some notes about using SSH with Mercurial:
470 - SSH requires an accessible shell account on the destination
474 - SSH requires an accessible shell account on the destination
471 machine and a copy of hg in the remote path or specified with as
475 machine and a copy of hg in the remote path or specified with as
472 remotecmd.
476 remotecmd.
473 - path is relative to the remote user's home directory by default.
477 - path is relative to the remote user's home directory by default.
474 Use an extra slash at the start of a path to specify an absolute path:
478 Use an extra slash at the start of a path to specify an absolute path:
475 ssh://example.com//tmp/repository
479 ssh://example.com//tmp/repository
476 - Mercurial doesn't use its own compression via SSH; the right
480 - Mercurial doesn't use its own compression via SSH; the right
477 thing to do is to configure it in your ~/.ssh/config, e.g.:
481 thing to do is to configure it in your ~/.ssh/config, e.g.:
478 Host *.mylocalnetwork.example.com
482 Host *.mylocalnetwork.example.com
479 Compression no
483 Compression no
480 Host *
484 Host *
481 Compression yes
485 Compression yes
482 Alternatively specify "ssh -C" as your ssh command in your hgrc
486 Alternatively specify "ssh -C" as your ssh command in your hgrc
483 or with the --ssh command line option.
487 or with the --ssh command line option.
484
488
485 These URLs can all be stored in your hgrc with path aliases under
489 These URLs can all be stored in your hgrc with path aliases under
486 the [paths] section like so:
490 the [paths] section like so:
487 [paths]
491 [paths]
488 alias1 = URL1
492 alias1 = URL1
489 alias2 = URL2
493 alias2 = URL2
490 ...
494 ...
491
495
492 You can then use the alias for any command that uses a URL (for
496 You can then use the alias for any command that uses a URL (for
493 example 'hg pull alias1' would pull from the 'alias1' path).
497 example 'hg pull alias1' would pull from the 'alias1' path).
494
498
495 Two path aliases are special because they are used as defaults
499 Two path aliases are special because they are used as defaults
496 when you do not provide the URL to a command:
500 when you do not provide the URL to a command:
497
501
498 default:
502 default:
499 When you create a repository with hg clone, the clone command
503 When you create a repository with hg clone, the clone command
500 saves the location of the source repository as the new
504 saves the location of the source repository as the new
501 repository's 'default' path. This is then used when you omit
505 repository's 'default' path. This is then used when you omit
502 path from push- and pull-like commands (including incoming and
506 path from push- and pull-like commands (including incoming and
503 outgoing).
507 outgoing).
504
508
505 default-push:
509 default-push:
506 The push command will look for a path named 'default-push', and
510 The push command will look for a path named 'default-push', and
507 prefer it over 'default' if both are defined.
511 prefer it over 'default' if both are defined.
508 ''')),
512 ''')),
509 (["extensions"], _("Using additional features"), extshelp),
513 (["extensions"], _("Using additional features"), extshelp),
510 )
514 )
General Comments 0
You need to be logged in to leave comments. Login now