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