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