56     extensions. Extensions may add new commands, add options to existing

    56     extensions. Extensions may add new commands, add options to

    57     commands, change the default behavior of commands, or implement hooks.

    57     existing commands, change the default behavior of commands, or

    58 

    58     implement hooks.

    59     Extensions are not loaded by default for a variety of reasons: they can

    59 

    60     increase startup overhead; they may be meant for advanced usage only; they

    60     Extensions are not loaded by default for a variety of reasons:

    61     may provide potentially dangerous abilities (such as letting you destroy

    61     they can increase startup overhead; they may be meant for advanced

    62     or modify history); they might not be ready for prime time; or they may

    62     usage only; they may provide potentially dangerous abilities (such

    63     alter some usual behaviors of stock Mercurial. It is thus up to the user

    63     as letting you destroy or modify history); they might not be ready

    64     to activate extensions as needed.

    64     for prime time; or they may alter some usual behaviors of stock

    65 

    65     Mercurial. It is thus up to the user to activate extensions as

    66     To enable the "foo" extension, either shipped with Mercurial or in the

    66     needed.

    67     Python search path, create an entry for it in your hgrc, like this::

    67 

    68     To enable the "foo" extension, either shipped with Mercurial or in

    69     the Python search path, create an entry for it in your hgrc, like

    70     this::

    77     To explicitly disable an extension enabled in an hgrc of broader scope,

    80     To explicitly disable an extension enabled in an hgrc of broader

    78     prepend its path with !::

    81     scope, prepend its path with !::

   123     This is the internal representation format for dates. unixtime is the

   126     This is the internal representation format for dates. unixtime is

   124     number of seconds since the epoch (1970-01-01 00:00 UTC). offset is the

   127     the number of seconds since the epoch (1970-01-01 00:00 UTC).

   125     offset of the local timezone, in seconds west of UTC (negative if the

   128     offset is the offset of the local timezone, in seconds west of UTC

   126     timezone is east of UTC).

   129     (negative if the timezone is east of UTC).

   138     Mercurial accepts several notations for identifying one or more files at a

   141     Mercurial accepts several notations for identifying one or more

   139     time.

   142     files at a time.

   140 

   143 

   141     By default, Mercurial treats filenames as shell-style extended glob

   144     By default, Mercurial treats filenames as shell-style extended

   142     patterns.

   145     glob patterns.

   146     To use a plain path name without any pattern matching, start it with

   149     To use a plain path name without any pattern matching, start it

   147     "path:". These path names must completely match starting at the current

   150     with "path:". These path names must completely match starting at

   148     repository root.

   151     the current repository root.

   149 

   152 

   150     To use an extended glob, start a name with "glob:". Globs are rooted at

   153     To use an extended glob, start a name with "glob:". Globs are

   151     the current directory; a glob such as "``*.c``" will only match files in the

   154     rooted at the current directory; a glob such as "``*.c``" will

   152     current directory ending with ".c".

   155     only match files in the current directory ending with ".c".

   153 

   156 

   154     The supported glob syntax extensions are "``**``" to match any string across

   157     The supported glob syntax extensions are "``**``" to match any

   155     path separators and "{a,b}" to mean "a or b".

   158     string across path separators and "{a,b}" to mean "a or b".

   156 

   159 

   157     To use a Perl/Python regular expression, start a name with "re:". Regexp

   160     To use a Perl/Python regular expression, start a name with "re:".

   158     pattern matching is anchored at the root of the repository.

   161     Regexp pattern matching is anchored at the root of the repository.

   162       path:foo/bar   a name bar in a directory named foo in the root of

   165       path:foo/bar   a name bar in a directory named foo in the root

   163                      the repository

   166                      of the repository

   185     Path to the 'hg' executable, automatically passed when running hooks,

   188     Path to the 'hg' executable, automatically passed when running

   186     extensions or external tools. If unset or empty, this is the hg

   189     hooks, extensions or external tools. If unset or empty, this is

   187     executable's name if it's frozen, or an executable named 'hg' (with

   190     the hg executable's name if it's frozen, or an executable named

   188     %PATHEXT% [defaulting to COM/EXE/BAT/CMD] extensions on Windows) is

   191     'hg' (with %PATHEXT% [defaulting to COM/EXE/BAT/CMD] extensions on

   189     searched.

   192     Windows) is searched.

   197     This overrides the default locale setting detected by Mercurial. This

   200     This overrides the default locale setting detected by Mercurial.

   198     setting is used to convert data including usernames, changeset

   201     This setting is used to convert data including usernames,

   199     descriptions, tag names, and branches. This setting can be overridden with

   202     changeset descriptions, tag names, and branches. This setting can

   200     the --encoding command-line option.

   203     be overridden with the --encoding command-line option.

   203     This sets Mercurial's behavior for handling unknown characters while

   206     This sets Mercurial's behavior for handling unknown characters

   204     transcoding user input. The default is "strict", which causes Mercurial to

   207     while transcoding user input. The default is "strict", which

   205     abort if it can't map a character. Other settings include "replace", which

   208     causes Mercurial to abort if it can't map a character. Other

   206     replaces unknown characters, and "ignore", which drops them. This setting

   209     settings include "replace", which replaces unknown characters, and

   207     can be overridden with the --encodingmode command-line option.

   210     "ignore", which drops them. This setting can be overridden with

   211     the --encodingmode command-line option.

   210     An executable to use for resolving merge conflicts. The program will be

   214     An executable to use for resolving merge conflicts. The program

   211     executed with three arguments: local file, remote file, ancestor file.

   215     will be executed with three arguments: local file, remote file,

   216     ancestor file.

   216     A list of files or directories to search for hgrc files. Item separator is

   221     A list of files or directories to search for hgrc files. Item

   217     ":" on Unix, ";" on Windows. If HGRCPATH is not set, platform default

   222     separator is ":" on Unix, ";" on Windows. If HGRCPATH is not set,

   218     search path is used. If empty, only the .hg/hgrc from the current

   223     platform default search path is used. If empty, only the .hg/hgrc

   219     repository is read.

   224     from the current repository is read.

   227     This is the string used as the author of a commit. If not set, available

   232     This is the string used as the author of a commit. If not set,

   228     values will be considered in this order:

   233     available values will be considered in this order:

   248     Sometimes Mercurial needs to open a text file in an editor for a user to

   253     Sometimes Mercurial needs to open a text file in an editor for a

   249     modify, for example when writing commit messages. The editor it uses is

   254     user to modify, for example when writing commit messages. The

   250     determined by looking at the environment variables HGEDITOR, VISUAL and

   255     editor it uses is determined by looking at the environment

   251     EDITOR, in that order. The first non-empty one is chosen. If all of them

   256     variables HGEDITOR, VISUAL and EDITOR, in that order. The first

   252     are empty, the editor defaults to 'vi'.

   257     non-empty one is chosen. If all of them are empty, the editor

   258     defaults to 'vi'.

   255     This is used by Python to find imported modules and may need to be set

   261     This is used by Python to find imported modules and may need to be

   256     appropriately if this Mercurial is not installed system-wide.

   262     set appropriately if this Mercurial is not installed system-wide.

   263     A plain integer is treated as a revision number. Negative integers are

   269     A plain integer is treated as a revision number. Negative integers

   264     treated as topological offsets from the tip, with -1 denoting the tip. As

   270     are treated as topological offsets from the tip, with -1 denoting

   265     such, negative numbers are only useful if you've memorized your local tree

   271     the tip. As such, negative numbers are only useful if you've

   266     numbers and want to save typing a single digit. This editor suggests copy

   272     memorized your local tree numbers and want to save typing a single

   267     and paste.

   273     digit. This editor suggests copy and paste.

   268 

   274 

   269     A 40-digit hexadecimal string is treated as a unique revision identifier.

   275     A 40-digit hexadecimal string is treated as a unique revision

   270 

   276     identifier.

   271     A hexadecimal string less than 40 characters long is treated as a unique

   277 

   272     revision identifier, and referred to as a short-form identifier. A

   278     A hexadecimal string less than 40 characters long is treated as a

   273     short-form identifier is only valid if it is the prefix of exactly one

   279     unique revision identifier, and referred to as a short-form

   274     full-length identifier.

   280     identifier. A short-form identifier is only valid if it is the

   275 

   281     prefix of exactly one full-length identifier.

   276     Any other string is treated as a tag name, which is a symbolic name

   282 

   277     associated with a revision identifier. Tag names may not contain the ":"

   283     Any other string is treated as a tag name, which is a symbolic

   278     character.

   284     name associated with a revision identifier. Tag names may not

   279 

   285     contain the ":" character.

   280     The reserved name "tip" is a special tag that always identifies the most

   286 

   281     recent revision.

   287     The reserved name "tip" is a special tag that always identifies

   282 

   288     the most recent revision.

   283     The reserved name "null" indicates the null revision. This is the revision

   289 

   284     of an empty repository, and the parent of revision 0.

   290     The reserved name "null" indicates the null revision. This is the

   285 

   291     revision of an empty repository, and the parent of revision 0.

   286     The reserved name "." indicates the working directory parent. If no

   292 

   287     working directory is checked out, it is equivalent to null. If an

   293     The reserved name "." indicates the working directory parent. If

   288     uncommitted merge is in progress, "." is the revision of the first parent.

   294     no working directory is checked out, it is equivalent to null. If

   295     an uncommitted merge is in progress, "." is the revision of the

   296     first parent.

   293     When Mercurial accepts more than one revision, they may be specified

   301     When Mercurial accepts more than one revision, they may be

   294     individually, or provided as a topologically continuous range, separated

   302     specified individually, or provided as a topologically continuous

   295     by the ":" character.

   303     range, separated by the ":" character.

   296 

   304 

   297     The syntax of range notation is [BEGIN]:[END], where BEGIN and END are

   305     The syntax of range notation is [BEGIN]:[END], where BEGIN and END

   298     revision identifiers. Both BEGIN and END are optional. If BEGIN is not

   306     are revision identifiers. Both BEGIN and END are optional. If

   299     specified, it defaults to revision number 0. If END is not specified, it

   307     BEGIN is not specified, it defaults to revision number 0. If END

   300     defaults to the tip. The range ":" thus means "all revisions".

   308     is not specified, it defaults to the tip. The range ":" thus means

   301 

   309     "all revisions".

   302     If BEGIN is greater than END, revisions are treated in reverse order.

   310 

   303 

   311     If BEGIN is greater than END, revisions are treated in reverse

   304     A range acts as a closed interval. This means that a range of 3:5 gives 3,

   312     order.

   305     4 and 5. Similarly, a range of 9:6 gives 9, 8, 7, and 6.

   313 

   314     A range acts as a closed interval. This means that a range of 3:5

   315     gives 3, 4 and 5. Similarly, a range of 9:6 gives 9, 8, 7, and 6.

   310     Mercurial's default format for showing changes between two versions of a

   320     Mercurial's default format for showing changes between two

   311     file is compatible with the unified format of GNU diff, which can be used

   321     versions of a file is compatible with the unified format of GNU

   312     by GNU patch and many other standard tools.

   322     diff, which can be used by GNU patch and many other standard

   323     tools.

   322     Mercurial also supports the extended diff format from the git VCS which

   333     Mercurial also supports the extended diff format from the git VCS

   323     addresses these limitations. The git diff format is not produced by

   334     which addresses these limitations. The git diff format is not

   324     default because a few widespread tools still do not understand this

   335     produced by default because a few widespread tools still do not

   325     format.

   336     understand this format.

   326 

   337 

   327     This means that when generating diffs from a Mercurial repository (e.g.

   338     This means that when generating diffs from a Mercurial repository

   328     with "hg export"), you should be careful about things like file copies and

   339     (e.g. with "hg export"), you should be careful about things like

   329     renames or other things mentioned above, because when applying a standard

   340     file copies and renames or other things mentioned above, because

   330     diff to a different repository, this extra information is lost.

   341     when applying a standard diff to a different repository, this

   331     Mercurial's internal operations (like push and pull) are not affected by

   342     extra information is lost. Mercurial's internal operations (like

   332     this, because they use an internal binary format for communicating

   343     push and pull) are not affected by this, because they use an

   333     changes.

   344     internal binary format for communicating changes.

   334 

   345 

   335     To make Mercurial produce the git extended diff format, use the --git

   346     To make Mercurial produce the git extended diff format, use the

   336     option available for many commands, or set 'git = True' in the [diff]

   347     --git option available for many commands, or set 'git = True' in

   337     section of your hgrc. You do not need to set this option when importing

   348     the [diff] section of your hgrc. You do not need to set this

   338     diffs in this format or using them in the mq extension.

   349     option when importing diffs in this format or using them in the mq

   350     extension.

   342     Mercurial allows you to customize output of commands through templates.

   354     Mercurial allows you to customize output of commands through

   343     You can either pass in a template from the command line, via the

   355     templates. You can either pass in a template from the command

   344     --template option, or select an existing template-style (--style).

   356     line, via the --template option, or select an existing

   345 

   357     template-style (--style).

   346     You can customize output for any "log-like" command: log, outgoing,

   358 

   347     incoming, tip, parents, heads and glog.

   359     You can customize output for any "log-like" command: log,

   348 

   360     outgoing, incoming, tip, parents, heads and glog.

   349     Three styles are packaged with Mercurial: default (the style used when no

   361 

   350     explicit preference is passed), compact and changelog. Usage:

   362     Three styles are packaged with Mercurial: default (the style used

   363     when no explicit preference is passed), compact and changelog.

   364     Usage:

   354     A template is a piece of text, with markup to invoke variable expansion:

   368     A template is a piece of text, with markup to invoke variable

   369     expansion:

   359     Strings in curly braces are called keywords. The availability of keywords

   374     Strings in curly braces are called keywords. The availability of

   360     depends on the exact context of the templater. These keywords are usually

   375     keywords depends on the exact context of the templater. These

   361     available for templating a log-like command:

   376     keywords are usually available for templating a log-like command:

   364     - branches: String. The name of the branch on which the changeset was

   379     - branches: String. The name of the branch on which the changeset

   365       committed. Will be empty if the branch name was default.

   380       was committed. Will be empty if the branch name was default.

   366     - date: Date information. The date when the changeset was committed.

   381     - date: Date information. The date when the changeset was

   382       committed.

   368     - diffstat: String. Statistics of changes with the following format:

   384     - diffstat: String. Statistics of changes with the following

   369       "modified files: +added/-removed lines"

   385       format: "modified files: +added/-removed lines"

   370     - files: List of strings. All files modified, added, or removed by this

   386     - files: List of strings. All files modified, added, or removed by

   371       changeset.

   387       this changeset.

   375     - node: String. The changeset identification hash, as a 40-character

   391     - node: String. The changeset identification hash, as a

   376       hexadecimal string.

   392       40-character hexadecimal string.

   381     The "date" keyword does not produce human-readable output. If you want to

   397     The "date" keyword does not produce human-readable output. If you

   382     use a date in your output, you can use a filter to process it. Filters are

   398     want to use a date in your output, you can use a filter to process

   383     functions which return a string based on the input variable. You can also

   399     it. Filters are functions which return a string based on the input

   384     use a chain of filters to get the desired output:

   400     variable. You can also use a chain of filters to get the desired

   401     output:

   391     - addbreaks: Any text. Add an XHTML "<br />" tag before the end of every

   408     - addbreaks: Any text. Add an XHTML "<br />" tag before the end of

   392       line except the last.

   409       every line except the last.

   393     - age: Date. Returns a human-readable date/time difference between the

   410     - age: Date. Returns a human-readable date/time difference between

   394       given date/time and the current date/time.

   411       the given date/time and the current date/time.

   395     - basename: Any text. Treats the text as a path, and returns the last

   412     - basename: Any text. Treats the text as a path, and returns the

   396       component of the path after splitting by the path separator (ignoring

   413       last component of the path after splitting by the path separator

   397       trailing separators). For example, "foo/bar/baz" becomes "baz" and

   414       (ignoring trailing separators). For example, "foo/bar/baz"

   398       "foo/bar//" becomes "bar".

   415       becomes "baz" and "foo/bar//" becomes "bar".

   403     - domain: Any text. Finds the first string that looks like an email

   420     - domain: Any text. Finds the first string that looks like an

   404       address, and extracts just the domain component. Example: 'User

   421       email address, and extracts just the domain component. Example:

   405       <user@example.com>' becomes 'example.com'.

   422       'User <user@example.com>' becomes 'example.com'.

   406     - email: Any text. Extracts the first string that looks like an email

   423     - email: Any text. Extracts the first string that looks like an

   407       address. Example: 'User <user@example.com>' becomes 'user@example.com'.

   424       email address. Example: 'User <user@example.com>' becomes

   408     - escape: Any text. Replaces the special XML/XHTML characters "&", "<" and

   425       'user@example.com'.

   409       ">" with XML entities.

   426     - escape: Any text. Replaces the special XML/XHTML characters "&",

   427       "<" and ">" with XML entities.

   414     - hgdate: Date. Returns the date as a pair of numbers: "1157407993 25200"

   432     - hgdate: Date. Returns the date as a pair of numbers: "1157407993

   415       (Unix timestamp, timezone offset).

   433       25200" (Unix timestamp, timezone offset).

   418     - obfuscate: Any text. Returns the input text rendered as a sequence of

   436     - obfuscate: Any text. Returns the input text rendered as a

   419       XML entities.

   437       sequence of XML entities.

   421     - rfc822date: Date. Returns a date using the same format used in email

   439     - rfc822date: Date. Returns a date using the same format used in

   422       headers.

   440       email headers.

   423     - short: Changeset hash. Returns the short form of a changeset hash, i.e.

   441     - short: Changeset hash. Returns the short form of a changeset

   424       a 12-byte hexadecimal string.

   442       hash, i.e. a 12-byte hexadecimal string.

   427     - tabindent: Any text. Returns the text, with every line except the first

   445     - tabindent: Any text. Returns the text, with every line except

   428       starting with a tab character.

   446       the first starting with a tab character.

   429     - urlescape: Any text. Escapes all "special" characters. For example, "foo

   447     - urlescape: Any text. Escapes all "special" characters. For

   430       bar" becomes "foo%20bar".

   448       example, "foo bar" becomes "foo%20bar".

   444     Paths in the local filesystem can either point to Mercurial repositories

   462     Paths in the local filesystem can either point to Mercurial

   445     or to bundle files (as created by 'hg bundle' or 'hg incoming --bundle').

   463     repositories or to bundle files (as created by 'hg bundle' or 'hg

   446 

   464     incoming --bundle').

   447     An optional identifier after # indicates a particular branch, tag, or

   465 

   448     changeset to use from the remote repository. See also 'hg help revisions'.

   466     An optional identifier after # indicates a particular branch, tag,

   449 

   467     or changeset to use from the remote repository. See also 'hg help

   450     Some features, such as pushing to http:// and https:// URLs are only

   468     revisions'.

   451     possible if the feature is explicitly enabled on the remote Mercurial

   469 

   452     server.

   470     Some features, such as pushing to http:// and https:// URLs are

   471     only possible if the feature is explicitly enabled on the remote

   472     Mercurial server.

   456     - SSH requires an accessible shell account on the destination machine and

   476     - SSH requires an accessible shell account on the destination

   457       a copy of hg in the remote path or specified with as remotecmd.

   477       machine and a copy of hg in the remote path or specified with as

   458     - path is relative to the remote user's home directory by default. Use an

   478       remotecmd.

   459       extra slash at the start of a path to specify an absolute path::

   479     - path is relative to the remote user's home directory by default.

   480       Use an extra slash at the start of a path to specify an absolute

   481       path::

   463     - Mercurial doesn't use its own compression via SSH; the right thing to do

   485     - Mercurial doesn't use its own compression via SSH; the right

   464       is to configure it in your ~/.ssh/config, e.g.::

   486       thing to do is to configure it in your ~/.ssh/config, e.g.::

   471       Alternatively specify "ssh -C" as your ssh command in your hgrc or with

   493       Alternatively specify "ssh -C" as your ssh command in your hgrc

   472       the --ssh command line option.

   494       or with the --ssh command line option.

   473 

   495 

   474     These URLs can all be stored in your hgrc with path aliases under the

   496     These URLs can all be stored in your hgrc with path aliases under

   475     [paths] section like so::

   497     the [paths] section like so::

   482     You can then use the alias for any command that uses a URL (for example

   504     You can then use the alias for any command that uses a URL (for

   483     'hg pull alias1' would pull from the 'alias1' path).

   505     example 'hg pull alias1' would pull from the 'alias1' path).

   484 

   506 

   485     Two path aliases are special because they are used as defaults when you do

   507     Two path aliases are special because they are used as defaults

   486     not provide the URL to a command:

   508     when you do not provide the URL to a command:

   489       When you create a repository with hg clone, the clone command saves the

   511       When you create a repository with hg clone, the clone command

   490       location of the source repository as the new repository's 'default'

   512       saves the location of the source repository as the new

   491       path. This is then used when you omit path from push- and pull-like

   513       repository's 'default' path. This is then used when you omit

   492       commands (including incoming and outgoing).

   514       path from push- and pull-like commands (including incoming and

   515       outgoing).

   495       The push command will look for a path named 'default-push', and prefer

   518       The push command will look for a path named 'default-push', and

   496       it over 'default' if both are defined.

   519       prefer it over 'default' if both are defined.