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