Mercurial > public > mercurial-scm > hg-stable

comparison mercurial/help.py @ 7678:b19850c7908a

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
help: some improvements for the templating topic
author Dirkjan Ochtman <dirkjan@ochtman.nl>
date Thu, 22 Jan 2009 14:19:29 +0100
parents 6a0bc2dc9da6
children e040f9d6b2f3
comparison
equal deleted inserted replaced
7677:6a0bc2dc9da6 7678:b19850c7908a
246 To make Mercurial produce the git extended diff format, use the 246 To make Mercurial produce the git extended diff format, use the
247 --git option available for many commands, or set 'git = True' in the 247 --git option available for many commands, or set 'git = True' in the
248 [diff] section of your hgrc. You do not need to set this option when 248 [diff] section of your hgrc. You do not need to set this option when
249 importing diffs in this format or using them in the mq extension. 249 importing diffs in this format or using them in the mq extension.
250 ''')), 250 ''')),
251 (['templating'], _('Usage of templates'), 251 (['templating'], _('Template Usage'),
252 _(r''' 252 _(r'''
253 Mercurial allows you to customize output of commands through 253 Mercurial allows you to customize output of commands through
254 templates. There is command line option for that and additionally 254 templates. You can either pass in a template from the command line,
255 styles, which are simply precanned templates that someone wrote. 255 via the --template option, or select an existing template-style (--style).
256 256
257 You can customize output for any "log-like" command, which currently 257 You can customize output for any "log-like" command: log, outgoing,
258 are: log, outgoing, incoming, tip, parents, heads and glog (if you have 258 incoming, tip, parents, heads and glog are all template-enabled.
259 graphlog extension enabled). 259
260 260 Three styles are packaged with Mercurial: default (the style used
261 There is three styles packaged with Mercurial: default (which is 261 when no explicit preference is passed), compact and changelog. Usage:
262 naturally what you see by default), compact and changelog. Usage: 262
263 263 $ hg log -r1 --style changelog
264 > hg log -r1 --style changelog 264
265 265 A template is a piece of text, with markup to invoke variable expansion:
266 Template is a piece of text, where parts marked with special syntax 266
267 are expanded, for example: 267 $ hg log -r1 --template "{node}\n"
268
269 > hg log -r1 --template "{node}\n"
270 b56ce7b07c52de7d5fd79fb89701ea538af65746 268 b56ce7b07c52de7d5fd79fb89701ea538af65746
271 269
272 Strings in curly brackets are called keywords and that's their 270 Strings in curly braces are called keywords. The availability of
273 current list: 271 keywords depends on the exact context of the templater. These keywords
272 are usually available for templating a log-like command:
274 273
275 - author: String. The unmodified author of the changeset. 274 - author: String. The unmodified author of the changeset.
276 - branches: String. The name of the branch on which the changeset 275 - branches: String. The name of the branch on which the changeset
277 was committed. Will be empty if the branch name was default. 276 was committed. Will be empty if the branch name was default.
278 - date: Date information. The date when the changeset was committed. 277 - date: Date information. The date when the changeset was committed.
279 - desc: String. The text of the changeset description. 278 - desc: String. The text of the changeset description.
280 - files: List of strings. All files modified, added, or removed by 279 - files: List of strings. All files modified, added, or removed by
281 this changeset. 280 this changeset.
282 - file_adds: List of strings. Files added by this changeset. 281 - file_adds: List of strings. Files added by this changeset.
282 - file_mods: List of strings. Files modified by this changeset.
283 - file_dels: List of strings. Files removed by this changeset. 283 - file_dels: List of strings. Files removed by this changeset.
284 - node: String. The changeset identification hash, as a 40-character 284 - node: String. The changeset identification hash, as a 40-character
285 hexadecimal string. 285 hexadecimal string.
286 - parents: List of strings. The parents of the changeset. 286 - parents: List of strings. The parents of the changeset.
287 - rev: Integer. The repository-local changeset revision number. 287 - rev: Integer. The repository-local changeset revision number.
288 - tags: List of strings. Any tags associated with the changeset. 288 - tags: List of strings. Any tags associated with the changeset.
289 289
290 But "date" keyword does not produce human-readable output, what 290 The "date" keyword does not produce human-readable output. If you
291 means that you should use a filter to process it. Filter is a 291 want to use a date in your output, you can use a filter to process it.
292 function which modifies the result of expanding a keyword and 292 Filters are functions which return a string based on the input variable.
293 Mercurial lets you specify a chain of filters: 293 You can also use a chain of filters to get the wanted output:
294 294
295 > hg tip --template "{date|isodate}\n" 295 $ hg tip --template "{date|isodate}\n"
296 2008-08-21 18:22 +0000 296 2008-08-21 18:22 +0000
297 297
298 List of filters: 298 List of filters:
299 299
300 - addbreaks: Any text. Add an XHTML "<br/>" tag before the end of 300 - addbreaks: Any text. Add an XHTML "<br />" tag before the end of
301 every line except the last. 301 every line except the last.
302 - age: Date. Render the age of the date. 302 - age: Date. Returns a human-readable age for the given date.
303 - basename: Any text. Treat the text as a path, and return the 303 - basename: Any text. Treats the text as a path, and returns the
304 basename. For example, "foo/bar/baz" becomes "baz". 304 basename. For example, "foo/bar/baz" becomes "baz".
305 - date: Date. Render a date in a Unix date command format, but with 305 - date: Date. Returns a date in a Unix date command format, including
306 timezone included: "Mon Sep 04 15:13:13 2006 0700". 306 the timezone: "Mon Sep 04 15:13:13 2006 0700".
307 - domain: Any text. Finds the first string that looks like an email 307 - domain: Any text. Finds the first string that looks like an email
308 address, and extract just the domain component. 308 address, and extracts just the domain component.
309 - email: Any text. Extract the first string that looks like an email 309 - email: Any text. Extracts the first string that looks like an email
310 address. 310 address.
311 - escape: Any text. Replace the special XML/XHTML characters "&", 311 - escape: Any text. Replaces the special XML/XHTML characters "&",
312 "<" and ">" with XML entities. 312 "<" and ">" with XML entities.
313 - fill68: Any text. Wrap the text to fit in 68 columns. 313 - fill68: Any text. Wraps the text to fit in 68 columns.
314 - fill76: Any text. Wrap the text to fit in 76 columns. 314 - fill76: Any text. Wraps the text to fit in 76 columns.
315 - firstline: Any text. Yield the first line of text. 315 - firstline: Any text. Returns the first line of text.
316 - hgdate: Date. Render the date as a pair of readable numbers: 316 - hgdate: Date. Returns the date as a pair of numbers:
317 "1157407993 25200". 317 "1157407993 25200" (Unix timestamp, timezone offset).
318 - isodate: Date. Render the date in ISO 8601 format. 318 - isodate: Date. Returns the date in ISO 8601 format.
319 - obfuscate: Any text. Yield the input text rendered as a sequence 319 - obfuscate: Any text. Returns the input text rendered as a sequence
320 of XML entities. 320 of XML entities.
321 - person: Any text. Yield the text before an email address. 321 - person: Any text. Returns the text before an email address.
322 - rfc822date: date keyword. Render a date using the same format used 322 - rfc822date: Date. Returns a date using the same format used
323 in email headers. 323 in email headers.
324 - short: Changeset hash. Yield the short form of a changeset hash, 324 - short: Changeset hash. Returns the short form of a changeset hash,
325 i.e. a 12-byte hexadecimal string. 325 i.e. a 12-byte hexadecimal string.
326 - shortdate: Date. Render date like "2006-09-04". 326 - shortdate: Date. Returns a date like "2006-09-04".
327 - strip: Any text. Strip all leading and trailing whitespace. 327 - strip: Any text. Strips all leading and trailing whitespace.
328 - tabindent: Any text. Yield the text, with every line except the 328 - tabindent: Any text. Returns the text, with every line except the
329 first starting with a tab character. 329 first starting with a tab character.
330 - urlescape: Any text. Escape all "special" characters. For example, 330 - urlescape: Any text. Escapes all "special" characters. For example,
331 foo bar becomes foo%20bar. 331 "foo bar" becomes "foo%20bar".
332 - user: Any text. Return the "user" portion of an email address. 332 - user: Any text. Returns the user portion of an email address.
333 ''')), 333 ''')),
334 ) 334 )