diff options
Diffstat (limited to 'mercurial/help')
| -rw-r--r-- | mercurial/help/config.txt | 567 | ||||
| -rw-r--r-- | mercurial/help/filesets.txt | 2 | ||||
| -rw-r--r-- | mercurial/help/glossary.txt | 23 | ||||
| -rw-r--r-- | mercurial/help/hgignore.txt | 17 | ||||
| -rw-r--r-- | mercurial/help/hgweb.txt | 71 | ||||
| -rw-r--r-- | mercurial/help/merge-tools.txt | 32 | ||||
| -rw-r--r-- | mercurial/help/patterns.txt | 4 | ||||
| -rw-r--r-- | mercurial/help/phases.txt | 84 | ||||
| -rw-r--r-- | mercurial/help/revisions.txt | 12 | ||||
| -rw-r--r-- | mercurial/help/revsets.txt | 7 | ||||
| -rw-r--r-- | mercurial/help/subrepos.txt | 68 |
11 files changed, 321 insertions, 566 deletions
diff --git a/mercurial/help/config.txt b/mercurial/help/config.txt index 557948b..52c2fee 100644 --- a/mercurial/help/config.txt +++ b/mercurial/help/config.txt @@ -13,7 +13,7 @@ The above entries will be referred to as ``ui.username`` and ``ui.verbose``, respectively. See the Syntax section below. Files -===== +----- Mercurial reads configuration data from several files, if they exist. These files do not exist by default and you will have to create the @@ -28,17 +28,16 @@ alphabetical order, later ones overriding earlier ones. Where multiple paths are given below, settings from earlier paths override later ones. -| (All) ``<repo>/.hg/hgrc`` +| (Unix, Windows) ``<repo>/.hg/hgrc`` Per-repository configuration options that only apply in a particular repository. This file is not version-controlled, and will not get transferred during a "clone" operation. Options in this file override options in all other configuration files. On - Plan 9 and Unix, most of this file will be ignored if it doesn't - belong to a trusted user or to a trusted group. See the documentation - for the ``[trusted]`` section below for more details. + Unix, most of this file will be ignored if it doesn't belong to a + trusted user or to a trusted group. See the documentation for the + ``[trusted]`` section below for more details. -| (Plan 9) ``$home/lib/hgrc`` | (Unix) ``$HOME/.hgrc`` | (Windows) ``%USERPROFILE%\.hgrc`` | (Windows) ``%USERPROFILE%\Mercurial.ini`` @@ -51,8 +50,6 @@ ones. directory. Options in these files override per-system and per-installation options. -| (Plan 9) ``/lib/mercurial/hgrc`` -| (Plan 9) ``/lib/mercurial/hgrc.d/*.rc`` | (Unix) ``/etc/mercurial/hgrc`` | (Unix) ``/etc/mercurial/hgrc.d/*.rc`` @@ -61,8 +58,6 @@ ones. executed by any user in any directory. Options in these files override per-installation options. -| (Plan 9) ``<install-root>/lib/mercurial/hgrc`` -| (Plan 9) ``<install-root>/lib/mercurial/hgrc.d/*.rc`` | (Unix) ``<install-root>/etc/mercurial/hgrc`` | (Unix) ``<install-root>/etc/mercurial/hgrc.d/*.rc`` @@ -83,10 +78,12 @@ ones. keys contain PATH-like strings, every part of which must reference a ``Mercurial.ini`` file or be a directory where ``*.rc`` files will be read. Mercurial checks each of these locations in the specified - order until one or more configuration files are detected. + order until one or more configuration files are detected. If the + pywin32 extensions are not installed, Mercurial will only look for + site-wide configuration in ``C:\Mercurial\Mercurial.ini``. Syntax -====== +------ A configuration file consists of sections, led by a ``[section]`` header and followed by ``name = value`` entries (sometimes called @@ -171,14 +168,14 @@ quotation marks at the beginning of a word is counted as a quotation (e.g., ``foo"bar baz`` is the list of ``foo"bar`` and ``baz``). Sections -======== +-------- This section describes the different sections that may appear in a Mercurial configuration file, the purpose of each section, its possible keys, and their possible values. ``alias`` ---------- +""""""""" Defines command aliases. Aliases allow you to define your own commands in terms of other @@ -209,7 +206,7 @@ An alias can start with an exclamation point (``!``) to make it a shell alias. A shell alias is executed with the shell and will let you run arbitrary commands. As an example, :: - echo = !echo $@ + echo = !echo will let you do ``hg echo foo`` to have ``foo`` printed in your terminal. A better example might be:: @@ -219,43 +216,15 @@ terminal. A better example might be:: which will make ``hg purge`` delete all unknown files in the repository in the same manner as the purge extension. -Positional arguments like ``$1``, ``$2``, etc. in the alias definition -expand to the command arguments. Unmatched arguments are -removed. ``$0`` expands to the alias name and ``$@`` expands to all -arguments separated by a space. These expansions happen before the -command is passed to the shell. - -Shell aliases are executed in an environment where ``$HG`` expands to +Shell aliases are executed in an environment where ``$HG`` expand to the path of the Mercurial that was used to execute the alias. This is useful when you want to call further Mercurial commands in a shell alias, as was done above for the purge alias. In addition, -``$HG_ARGS`` expands to the arguments given to Mercurial. In the ``hg +``$HG_ARGS`` expand to the arguments given to Mercurial. In the ``hg echo foo`` call above, ``$HG_ARGS`` would expand to ``echo foo``. -.. note:: Some global configuration options such as ``-R`` are - processed before shell aliases and will thus not be passed to - aliases. - - -``annotate`` ------------- - -Settings used when displaying file annotations. All values are -Booleans and default to False. See ``diff`` section for related -options for the diff command. - -``ignorews`` - Ignore white space when comparing lines. - -``ignorewsamount`` - Ignore changes in the amount of white space. - -``ignoreblanklines`` - Ignore changes whose lines are all blank. - - ``auth`` --------- +"""""""" Authentication credentials for HTTP authentication. This section allows you to store usernames and passwords for use when logging @@ -322,7 +291,7 @@ for credentials as usual if required by the remote. ``decode/encode`` ------------------ +""""""""""""""""" Filters for transforming files on checkout/checkin. This would typically be used for newline processing or other @@ -369,7 +338,7 @@ format. We suggest you use the ``eol`` extension for convenience. ``defaults`` ------------- +"""""""""""" (defaults are deprecated. Don't use them. Use aliases instead) @@ -389,11 +358,10 @@ to the aliases of the commands defined. ``diff`` --------- +"""""""" -Settings used when displaying diffs. Everything except for ``unified`` -is a Boolean and defaults to False. See ``annotate`` section for -related options for the annotate command. +Settings used when displaying diffs. Everything except for ``unified`` is a +Boolean and defaults to False. ``git`` Use git extended diff format. @@ -417,7 +385,7 @@ related options for the annotate command. Number of lines of context to show. ``email`` ---------- +""""""""" Settings for extensions that send email messages. @@ -472,7 +440,7 @@ Email example:: ``extensions`` --------------- +"""""""""""""" Mercurial has an extension mechanism for adding new features. To enable an extension, create an entry for it in this section. @@ -498,8 +466,26 @@ Example for ``~/.hgrc``:: myfeature = ~/.hgext/myfeature.py +``hostfingerprints`` +"""""""""""""""""""" + +Fingerprints of the certificates of known HTTPS servers. +A HTTPS connection to a server with a fingerprint configured here will +only succeed if the servers certificate matches the fingerprint. +This is very similar to how ssh known hosts works. +The fingerprint is the SHA-1 hash value of the DER encoded certificate. +The CA chain and web.cacerts is not used for servers with a fingerprint. + +For example:: + + [hostfingerprints] + hg.intevation.org = 38:76:52:7c:87:26:9a:8f:4a:f8:d3:de:08:45:3b:ea:d6:4b:ee:cc + +This feature is only supported when using Python 2.6 or later. + + ``format`` ----------- +"""""""""" ``usestore`` Enable or disable the "store" repository format which improves @@ -525,45 +511,128 @@ Example for ``~/.hgrc``:: option ensures that the on-disk format of newly created repositories will be compatible with Mercurial before version 1.7. -``graph`` ---------- +``merge-patterns`` +"""""""""""""""""" -Web graph view configuration. This section let you change graph -elements display properties by branches, for instance to make the -``default`` branch stand out. +This section specifies merge tools to associate with particular file +patterns. Tools matched here will take precedence over the default +merge tool. Patterns are globs by default, rooted at the repository +root. -Each line has the following format:: +Example:: + + [merge-patterns] + **.c = kdiff3 + **.jpg = myimgmerge - <branch>.<argument> = <value> +``merge-tools`` +""""""""""""""" -where ``<branch>`` is the name of the branch being -customized. Example:: +This section configures external merge tools to use for file-level +merges. - [graph] - # 2px width - default.width = 2 - # red color - default.color = FF0000 +Example ``~/.hgrc``:: + + [merge-tools] + # Override stock tool location + kdiff3.executable = ~/bin/kdiff3 + # Specify command line + kdiff3.args = $base $local $other -o $output + # Give higher priority + kdiff3.priority = 1 + + # Define new tool + myHtmlTool.args = -m $local $other $base $output + myHtmlTool.regkey = Software\FooSoftware\HtmlMerge + myHtmlTool.priority = 1 Supported arguments: -``width`` - Set branch edges width in pixels. +``priority`` + The priority in which to evaluate this tool. + Default: 0. + +``executable`` + Either just the name of the executable or its pathname. On Windows, + the path can use environment variables with ${ProgramFiles} syntax. + Default: the tool name. + +``args`` + The arguments to pass to the tool executable. You can refer to the + files being merged as well as the output file through these + variables: ``$base``, ``$local``, ``$other``, ``$output``. + Default: ``$local $base $other`` + +``premerge`` + Attempt to run internal non-interactive 3-way merge tool before + launching external tool. Options are ``true``, ``false``, or ``keep`` + to leave markers in the file if the premerge fails. + Default: True + +``binary`` + This tool can merge binary files. Defaults to False, unless tool + was selected by file pattern match. + +``symlink`` + This tool can merge symlinks. Defaults to False, even if tool was + selected by file pattern match. + +``check`` + A list of merge success-checking options: + + ``changed`` + Ask whether merge was successful when the merged file shows no changes. + ``conflicts`` + Check whether there are conflicts even though the tool reported success. + ``prompt`` + Always prompt for merge success, regardless of success reported by tool. + +``checkchanged`` + True is equivalent to ``check = changed``. + Default: False + +``checkconflicts`` + True is equivalent to ``check = conflicts``. + Default: False + +``fixeol`` + Attempt to fix up EOL changes caused by the merge tool. + Default: False + +``gui`` + This tool requires a graphical interface to run. Default: False + +``regkey`` + Windows registry key which describes install location of this + tool. Mercurial will search for this key first under + ``HKEY_CURRENT_USER`` and then under ``HKEY_LOCAL_MACHINE``. + Default: None + +``regkeyalt`` + An alternate Windows registry key to try if the first key is not + found. The alternate key uses the same ``regname`` and ``regappend`` + semantics of the primary key. The most common use for this key + is to search for 32bit applications on 64bit operating systems. + Default: None + +``regname`` + Name of value to read from specified registry key. Defaults to the + unnamed (default) value. + +``regappend`` + String to append to the value read from the registry, typically + the executable name of the tool. + Default: None -``color`` - Set branch edges color in hexadecimal RGB notation. ``hooks`` ---------- +""""""""" Commands or Python functions that get automatically executed by various actions such as starting or finishing a commit. Multiple hooks can be run for the same action by appending a suffix to the action. Overriding a site-wide hook can be done by changing its -value or setting it to an empty string. Hooks can be prioritized -by adding a prefix of ``priority`` to the hook name on a new line -and setting the priority. The default priority is 0 if -not specified. +value or setting it to an empty string. Example ``.hg/hgrc``:: @@ -574,8 +643,6 @@ Example ``.hg/hgrc``:: incoming = incoming.email = /my/email/hook incoming.autobuild = /my/build/hook - # force autobuild hook to run before other incoming hooks - priority.incoming.autobuild = 1 Most hooks are run with environment variables set that give useful additional information. For each hook below, the environment @@ -732,26 +799,8 @@ If a Python hook returns a "true" value or raises an exception, this is treated as a failure. -``hostfingerprints`` --------------------- - -Fingerprints of the certificates of known HTTPS servers. -A HTTPS connection to a server with a fingerprint configured here will -only succeed if the servers certificate matches the fingerprint. -This is very similar to how ssh known hosts works. -The fingerprint is the SHA-1 hash value of the DER encoded certificate. -The CA chain and web.cacerts is not used for servers with a fingerprint. - -For example:: - - [hostfingerprints] - hg.intevation.org = 38:76:52:7c:87:26:9a:8f:4a:f8:d3:de:08:45:3b:ea:d6:4b:ee:cc - -This feature is only supported when using Python 2.6 or later. - - ``http_proxy`` --------------- +"""""""""""""" Used to access web-based Mercurial repositories through a HTTP proxy. @@ -774,122 +823,37 @@ proxy. Optional. Always use the proxy, even for localhost and any entries in ``http_proxy.no``. True or False. Default: False. -``merge-patterns`` ------------------- - -This section specifies merge tools to associate with particular file -patterns. Tools matched here will take precedence over the default -merge tool. Patterns are globs by default, rooted at the repository -root. - -Example:: - - [merge-patterns] - **.c = kdiff3 - **.jpg = myimgmerge - -``merge-tools`` ---------------- - -This section configures external merge tools to use for file-level -merges. - -Example ``~/.hgrc``:: - - [merge-tools] - # Override stock tool location - kdiff3.executable = ~/bin/kdiff3 - # Specify command line - kdiff3.args = $base $local $other -o $output - # Give higher priority - kdiff3.priority = 1 - - # Define new tool - myHtmlTool.args = -m $local $other $base $output - myHtmlTool.regkey = Software\FooSoftware\HtmlMerge - myHtmlTool.priority = 1 - -Supported arguments: - -``priority`` - The priority in which to evaluate this tool. - Default: 0. - -``executable`` - Either just the name of the executable or its pathname. On Windows, - the path can use environment variables with ${ProgramFiles} syntax. - Default: the tool name. - -``args`` - The arguments to pass to the tool executable. You can refer to the - files being merged as well as the output file through these - variables: ``$base``, ``$local``, ``$other``, ``$output``. - Default: ``$local $base $other`` - -``premerge`` - Attempt to run internal non-interactive 3-way merge tool before - launching external tool. Options are ``true``, ``false``, or ``keep`` - to leave markers in the file if the premerge fails. - Default: True - -``binary`` - This tool can merge binary files. Defaults to False, unless tool - was selected by file pattern match. - -``symlink`` - This tool can merge symlinks. Defaults to False, even if tool was - selected by file pattern match. - -``check`` - A list of merge success-checking options: - - ``changed`` - Ask whether merge was successful when the merged file shows no changes. - ``conflicts`` - Check whether there are conflicts even though the tool reported success. - ``prompt`` - Always prompt for merge success, regardless of success reported by tool. - -``checkchanged`` - True is equivalent to ``check = changed``. - Default: False +``smtp`` +"""""""" -``checkconflicts`` - True is equivalent to ``check = conflicts``. - Default: False +Configuration for extensions that need to send email messages. -``fixeol`` - Attempt to fix up EOL changes caused by the merge tool. - Default: False +``host`` + Host name of mail server, e.g. "mail.example.com". -``gui`` - This tool requires a graphical interface to run. Default: False +``port`` + Optional. Port to connect to on mail server. Default: 25. -``regkey`` - Windows registry key which describes install location of this - tool. Mercurial will search for this key first under - ``HKEY_CURRENT_USER`` and then under ``HKEY_LOCAL_MACHINE``. - Default: None +``tls`` + Optional. Method to enable TLS when connecting to mail server: starttls, + smtps or none. Default: none. -``regkeyalt`` - An alternate Windows registry key to try if the first key is not - found. The alternate key uses the same ``regname`` and ``regappend`` - semantics of the primary key. The most common use for this key - is to search for 32bit applications on 64bit operating systems. - Default: None +``username`` + Optional. User name for authenticating with the SMTP server. + Default: none. -``regname`` - Name of value to read from specified registry key. Defaults to the - unnamed (default) value. +``password`` + Optional. Password for authenticating with the SMTP server. If not + specified, interactive sessions will prompt the user for a + password; non-interactive sessions will fail. Default: none. -``regappend`` - String to append to the value read from the registry, typically - the executable name of the tool. - Default: None +``local_hostname`` + Optional. It's the hostname that the sender can use to identify + itself to the MTA. ``patch`` ---------- +""""""""" Settings used when applying patches, for instance through the 'import' command or with Mercurial Queues extension. @@ -907,7 +871,7 @@ command or with Mercurial Queues extension. ``paths`` ---------- +""""""""" Assigns symbolic names to repositories. The left side is the symbolic name, and the right gives the directory or URL that is the @@ -923,50 +887,18 @@ the following entries. Optional. Directory or URL to use when pushing if no destination is specified. -``phases`` ----------- - -Specifies default handling of phases. See :hg:`help phases` for more -information about working with phases. - -``publish`` - Controls draft phase behavior when working as a server. When true, - pushed changesets are set to public in both client and server and - pulled or cloned changesets are set to public in the client. - Default: True - -``new-commit`` - Phase of newly-created commits. - Default: draft ``profiling`` -------------- - -Specifies profiling type, format, and file output. Two profilers are -supported: an instrumenting profiler (named ``ls``), and a sampling -profiler (named ``stat``). - -In this section description, 'profiling data' stands for the raw data -collected during profiling, while 'profiling report' stands for a -statistical text report generated from the profiling data. The -profiling is done using lsprof. - -``type`` - The type of profiler to use. - Default: ls. - - ``ls`` - Use Python's built-in instrumenting profiler. This profiler - works on all platforms, but each line number it reports is the - first line of a function. This restriction makes it difficult to - identify the expensive parts of a non-trivial function. - ``stat`` - Use a third-party statistical profiler, statprof. This profiler - currently runs only on Unix systems, and is most useful for - profiling commands that run for longer than about 0.1 seconds. +""""""""""""" + +Specifies profiling format and file output. In this section +description, 'profiling data' stands for the raw data collected +during profiling, while 'profiling report' stands for a statistical +text report generated from the profiling data. The profiling is done +using lsprof. ``format`` - Profiling format. Specific to the ``ls`` instrumenting profiler. + Profiling format. Default: text. ``text`` @@ -978,22 +910,18 @@ profiling is done using lsprof. file, the generated file can directly be loaded into kcachegrind. -``frequency`` - Sampling frequency. Specific to the ``stat`` sampling profiler. - Default: 1000. - ``output`` File path where profiling data or report should be saved. If the file exists, it is replaced. Default: None, data is printed on stderr ``revsetalias`` ---------------- +""""""""""""""" Alias definitions for revsets. See :hg:`help revsets` for details. ``server`` ----------- +"""""""""" Controls generic server settings. @@ -1009,68 +937,31 @@ Controls generic server settings. the write lock while determining what data to transfer. Default is True. -``preferuncompressed`` - When set, clients will try to use the uncompressed streaming - protocol. Default is False. - ``validate`` Whether to validate the completeness of pushed changesets by checking that all new file revisions specified in manifests are present. Default is False. -``smtp`` --------- - -Configuration for extensions that need to send email messages. - -``host`` - Host name of mail server, e.g. "mail.example.com". - -``port`` - Optional. Port to connect to on mail server. Default: 25. - -``tls`` - Optional. Method to enable TLS when connecting to mail server: starttls, - smtps or none. Default: none. - -``username`` - Optional. User name for authenticating with the SMTP server. - Default: none. - -``password`` - Optional. Password for authenticating with the SMTP server. If not - specified, interactive sessions will prompt the user for a - password; non-interactive sessions will fail. Default: none. - -``local_hostname`` - Optional. It's the hostname that the sender can use to identify - itself to the MTA. - - ``subpaths`` ------------- +"""""""""""" -Subrepository source URLs can go stale if a remote server changes name -or becomes temporarily unavailable. This section lets you define -rewrite rules of the form:: +Defines subrepositories source locations rewriting rules of the form:: <pattern> = <replacement> -where ``pattern`` is a regular expression matching a subrepository -source URL and ``replacement`` is the replacement string used to -rewrite it. Groups can be matched in ``pattern`` and referenced in -``replacements``. For instance:: +Where ``pattern`` is a regular expression matching the source and +``replacement`` is the replacement string used to rewrite it. Groups +can be matched in ``pattern`` and referenced in ``replacements``. For +instance:: http://server/(.*)-hg/ = http://hg.server/\1/ rewrites ``http://server/foo-hg/`` into ``http://hg.server/foo/``. -Relative subrepository paths are first made absolute, and the -rewrite rules are then applied on the full (absolute) path. The rules -are applied in definition order. +All patterns are applied in definition order. ``trusted`` ------------ +""""""""""" Mercurial will not use the settings in the ``.hg/hgrc`` file from a repository if it doesn't belong to a trusted @@ -1094,7 +985,7 @@ user or service running Mercurial. ``ui`` ------- +"""""" User interface controls. @@ -1115,7 +1006,7 @@ User interface controls. Whether to commit modified subrepositories when committing the parent repository. If False and one subrepository has uncommitted changes, abort the commit. - Default is False. + Default is True. ``debug`` Print debugging information. True or False. Default is False. @@ -1164,10 +1055,6 @@ User interface controls. ``remotecmd`` remote command to use for clone/push/pull operations. Default is ``hg``. -``reportoldssl`` - Warn if an SSL certificate is unable to be due to using Python - 2.5 or earlier. True or False. Default is True. - ``report_untrusted`` Warn if a ``.hg/hgrc`` file is ignored due to not being owned by a trusted user or group. True or False. Default is True. @@ -1213,7 +1100,7 @@ User interface controls. ``web`` -------- +""""""" Web interface configuration. The settings in this section apply to both the builtin webserver (started by :hg:`serve`) and the script you @@ -1269,6 +1156,13 @@ The full set of options is: be present in this list. The contents of the allow_push list are examined after the deny_push list. +``guessmime`` + Control MIME types for raw download of file content. + Set to True to let hgweb guess the content type from the file + extension. This will serve HTML files as ``text/html`` and might + allow cross-site scripting attacks when serving untrusted + repositories. Default is False. + ``allow_read`` If the user has not already been denied repository access due to the contents of deny_read, this list determines whether to grant @@ -1294,46 +1188,30 @@ The full set of options is: authority certificates. Environment variables and ``~user`` constructs are expanded in the filename. If specified on the client, then it will verify the identity of remote HTTPS servers - with these certificates. + with these certificates. The form must be as follows:: + + -----BEGIN CERTIFICATE----- + ... (certificate in base64 PEM encoding) ... + -----END CERTIFICATE----- + -----BEGIN CERTIFICATE----- + ... (certificate in base64 PEM encoding) ... + -----END CERTIFICATE----- This feature is only supported when using Python 2.6 or later. If you wish to use it with earlier versions of Python, install the backported version of the ssl library that is available from ``http://pypi.python.org``. + You can use OpenSSL's CA certificate file if your platform has one. + On most Linux systems this will be ``/etc/ssl/certs/ca-certificates.crt``. + Otherwise you will have to generate this file manually. + To disable SSL verification temporarily, specify ``--insecure`` from command line. - You can use OpenSSL's CA certificate file if your platform has - one. On most Linux systems this will be - ``/etc/ssl/certs/ca-certificates.crt``. Otherwise you will have to - generate this file manually. The form must be as follows:: - - -----BEGIN CERTIFICATE----- - ... (certificate in base64 PEM encoding) ... - -----END CERTIFICATE----- - -----BEGIN CERTIFICATE----- - ... (certificate in base64 PEM encoding) ... - -----END CERTIFICATE----- - ``cache`` Whether to support caching in hgweb. Defaults to True. -``collapse`` - With ``descend`` enabled, repositories in subdirectories are shown at - a single level alongside repositories in the current path. With - ``collapse`` also enabled, repositories residing at a deeper level than - the current path are grouped behind navigable directory entries that - lead to the locations of these repositories. In effect, this setting - collapses each collection of repositories found within a subdirectory - into a single entry for that subdirectory. Default is False. - -``comparisoncontext`` - Number of lines of context to show in side-by-side file comparison. If - negative or the value ``full``, whole files are shown. Default is 5. - This setting can be overridden by a ``context`` request parameter to the - ``comparison`` command, taking the same values. - ``contact`` Name or email address of the person in charge of the repository. Defaults to ui.username or ``$EMAIL`` or "unknown" if unset or empty. @@ -1376,13 +1254,6 @@ The full set of options is: ``errorlog`` Where to output the error log. Default is stderr. -``guessmime`` - Control MIME types for raw download of file content. - Set to True to let hgweb guess the content type from the file - extension. This will serve HTML files as ``text/html`` and might - allow cross-site scripting attacks when serving untrusted - repositories. Default is False. - ``hidden`` Whether to hide the repository in the hgwebdir index. Default is False. @@ -1390,30 +1261,20 @@ The full set of options is: ``ipv6`` Whether to use IPv6. Default is False. -``logoimg`` - File name of the logo image that some templates display on each page. - The file name is relative to ``staticurl``. That is, the full path to - the logo image is "staticurl/logoimg". - If unset, ``hglogo.png`` will be used. - ``logourl`` Base URL to use for logos. If unset, ``http://mercurial.selenic.com/`` will be used. +``name`` + Repository name to use in the web interface. Default is current + working directory. + ``maxchanges`` Maximum number of changes to list on the changelog. Default is 10. ``maxfiles`` Maximum number of files to list per changeset. Default is 10. -``maxshortchanges`` - Maximum number of changes to list on the shortlog, graph or filelog - pages. Default is 60. - -``name`` - Repository name to use in the web interface. Default is current - working directory. - ``port`` Port to listen on. Default is 8000. diff --git a/mercurial/help/filesets.txt b/mercurial/help/filesets.txt index afad752..c929d79 100644 --- a/mercurial/help/filesets.txt +++ b/mercurial/help/filesets.txt @@ -52,7 +52,7 @@ Some sample queries: - Find C files in a non-standard encoding:: - hg locate "set:**.c and not encoding('UTF-8')" + hg locate "set:**.c and not encoding(ascii)" - Revert copies of large binary files:: diff --git a/mercurial/help/glossary.txt b/mercurial/help/glossary.txt index 59a9d03..074a31d 100644 --- a/mercurial/help/glossary.txt +++ b/mercurial/help/glossary.txt @@ -135,7 +135,7 @@ Child changeset See 'Changeset, child'. Close changeset - See 'Head, closed branch' + See 'Changeset, close'. Closed branch See 'Branch, closed'. @@ -212,11 +212,6 @@ Directory, working to the files introduced manually or by a merge. The repository metadata exists in the .hg directory inside the working directory. -Draft - Changesets in the draft phase have not been shared with publishing - repositories and may thus be safely changed by history-modifying - extensions. See :hg:`help phases`. - Graph See DAG and :hg:`help graphlog`. @@ -237,9 +232,6 @@ Head, closed branch closed when all its heads are closed and consequently is not listed by :hg:`branches`. - Closed heads can be re-opened by committing new changeset as the - child of the changeset that marks a head as closed. - Head, repository A topological head which has not been closed. @@ -308,15 +300,6 @@ Patch Example: "You will need to patch that revision." -Phase - A per-changeset state tracking how the changeset has been or - should be shared. See :hg:`help phases`. - -Public - Changesets in the public phase have been shared with publishing - repositories and are therefore considered immutable. See :hg:`help - phases`. - Pull An operation in which changesets in a remote repository which are not in the local repository are brought into the local @@ -368,10 +351,6 @@ Root A changeset that has only the null changeset as its parent. Most repositories have only a single root changeset. -Secret - Changesets in the secret phase may not be shared via push, pull, - or clone. See :hg:`help phases`. - Tag An alternative name given to a changeset. Tags can be used in all places where Mercurial expects a changeset ID, e.g., with diff --git a/mercurial/help/hgignore.txt b/mercurial/help/hgignore.txt index 3f82177..538f4b5 100644 --- a/mercurial/help/hgignore.txt +++ b/mercurial/help/hgignore.txt @@ -1,12 +1,12 @@ Synopsis -======== +-------- The Mercurial system uses a file called ``.hgignore`` in the root directory of a repository to control its behavior when it searches for files that it is not currently tracking. Description -=========== +----------- The working directory of a Mercurial repository will often contain files that should not be tracked by Mercurial. These include backup @@ -33,13 +33,8 @@ To control Mercurial's handling of files that it manages, many commands support the ``-I`` and ``-X`` options; see :hg:`help <command>` and :hg:`help patterns` for details. -Files that are already tracked are not affected by .hgignore, even -if they appear in .hgignore. An untracked file X can be explicitly -added with :hg:`add X`, even if X would be excluded by a pattern -in .hgignore. - Syntax -====== +------ An ignore file is a plain text file consisting of a list of patterns, with one pattern per line. Empty lines are skipped. The ``#`` @@ -68,12 +63,8 @@ the form ``*.c`` will match a file ending in ``.c`` in any directory, and a regexp pattern of the form ``\.c$`` will do the same. To root a regexp pattern, start it with ``^``. -.. note:: - Patterns specified in other than ``.hgignore`` are always rooted. - Please see :hg:`help patterns` for details. - Example -======= +------- Here is an example ignore file. :: diff --git a/mercurial/help/hgweb.txt b/mercurial/help/hgweb.txt index 9ac557e..fa901e6 100644 --- a/mercurial/help/hgweb.txt +++ b/mercurial/help/hgweb.txt @@ -1,50 +1,47 @@ Mercurial's internal web server, hgweb, can serve either a single -repository, or a tree of repositories. In the second case, repository -paths and global options can be defined using a dedicated -configuration file common to :hg:`serve`, ``hgweb.wsgi``, -``hgweb.cgi`` and ``hgweb.fcgi``. +repository, or a collection of them. In the latter case, a special +configuration file can be used to specify the repository paths to use +and global web configuration options. -This file uses the same syntax as other Mercurial configuration files -but recognizes only the following sections: +This file uses the same syntax as other Mercurial configuration files, +but only the following sections are recognized: - web - paths - collections -The ``web`` options are thorougly described in :hg:`help config`. +The ``web`` section can specify all the settings described in the web +section of the hgrc(5) documentation. See :hg:`help config` for +information on where to find the manual page. -The ``paths`` section maps URL paths to paths of repositories in the -filesystem. hgweb will not expose the filesystem directly - only -Mercurial repositories can be published and only according to the -configuration. - -The left hand side is the path in the URL. Note that hgweb reserves -subpaths like ``rev`` or ``file``, try using different names for -nested repositories to avoid confusing effects. - -The right hand side is the path in the filesystem. If the specified -path ends with ``*`` or ``**`` the filesystem will be searched -recursively for repositories below that point. -With ``*`` it will not recurse into the repositories it finds (except for -``.hg/patches``). -With ``**`` it will also search inside repository working directories -and possibly find subrepositories. - -In this example:: +The ``paths`` section provides mappings of physical repository +paths to virtual ones. For instance:: [paths] - /projects/a = /srv/tmprepos/a - /projects/b = c:/repos/b - / = /srv/repos/* - /user/bob = /home/bob/repos/** + projects/a = /foo/bar + projects/b = /baz/quux + web/root = /real/root/* + / = /real/root2/* + virtual/root2 = /real/root2/** - The first two entries make two repositories in different directories appear under the same directory in the web interface -- The third entry will publish every Mercurial repository found in - ``/srv/repos/``, for instance the repository ``/srv/repos/quux/`` - will appear as ``http://server/quux/`` -- The fourth entry will publish both ``http://server/user/bob/quux/`` - and ``http://server/user/bob/quux/testsubrepo/`` - -The ``collections`` section is deprecated and has been superseeded by -``paths``. +- The third entry maps every Mercurial repository found in '/real/root' + into 'web/root'. This format is preferred over the [collections] one, + since using absolute paths as configuration keys is not supported on every + platform (especially on Windows). +- The fourth entry is a special case mapping all repositories in + '/real/root2' in the root of the virtual directory. +- The fifth entry recursively finds all repositories under the real + root, and maps their relative paths under the virtual root. + +The ``collections`` section provides mappings of trees of physical +repositories paths to virtual ones, though the paths syntax is generally +preferred. For instance:: + + [collections] + /foo = /foo + +Here, the left side will be stripped off all repositories found in the +right side. Thus ``/foo/bar`` and ``foo/quux/baz`` will be listed as +``bar`` and ``quux/baz`` respectively. diff --git a/mercurial/help/merge-tools.txt b/mercurial/help/merge-tools.txt index b7ed1ea..7324fe4 100644 --- a/mercurial/help/merge-tools.txt +++ b/mercurial/help/merge-tools.txt @@ -17,7 +17,7 @@ conflict markers. Mercurial does not include any interactive merge programs but relies on external tools for that. Available merge tools -===================== +""""""""""""""""""""" External merge tools and their properties are configured in the merge-tools configuration section - see hgrc(5) - but they can often just @@ -34,13 +34,39 @@ GUI is available if the tool requires a GUI. There are some internal merge tools which can be used. The internal merge tools are: -.. internaltoolsmarker +``internal:merge`` + Uses the internal non-interactive simple merge algorithm for merging + files. It will fail if there are any conflicts and leave markers in + the partially merged file. + +``internal:fail`` + Rather than attempting to merge files that were modified on both + branches, it marks them as unresolved. The resolve command must be + used to resolve these conflicts. + +``internal:local`` + Uses the local version of files as the merged version. + +``internal:other`` + Uses the other version of files as the merged version. + +``internal:prompt`` + Asks the user which of the local or the other version to keep as + the merged version. + +``internal:dump`` + Creates three versions of the files to merge, containing the + contents of local, other and base. These files can then be used to + perform a merge manually. If the file to be merged is named + ``a.txt``, these files will accordingly be named ``a.txt.local``, + ``a.txt.other`` and ``a.txt.base`` and they will be placed in the + same directory as ``a.txt``. Internal tools are always available and do not require a GUI but will by default not handle symlinks or binary files. Choosing a merge tool -===================== +""""""""""""""""""""" Mercurial uses these rules when deciding which merge tool to use: diff --git a/mercurial/help/patterns.txt b/mercurial/help/patterns.txt index 30133a3..c13453e 100644 --- a/mercurial/help/patterns.txt +++ b/mercurial/help/patterns.txt @@ -6,10 +6,6 @@ patterns. Alternate pattern notations must be specified explicitly. -.. note:: - Patterns specified in ``.hgignore`` are not rooted. - Please see :hg:`help hgignore` for details. - To use a plain path name without any pattern matching, start it with ``path:``. These path names must completely match starting at the current repository root. diff --git a/mercurial/help/phases.txt b/mercurial/help/phases.txt deleted file mode 100644 index 19023dc..0000000 --- a/mercurial/help/phases.txt +++ /dev/null @@ -1,84 +0,0 @@ -What are phases? -================ - -Phases are a system for tracking which changesets have been or should -be shared. This helps prevent common mistakes when modifying history -(for instance, with the mq or rebase extensions). - -Each changeset in a repository is in one of the following phases: - - - public : changeset is visible on a public server - - draft : changeset is not yet published - - secret : changeset should not be pushed, pulled, or cloned - -These phases are ordered (public < draft < secret) and no changeset -can be in a lower phase than its ancestors. For instance, if a -changeset is public, all its ancestors are also public. Lastly, -changeset phases should only be changed towards the public phase. - -How are phases managed? -======================= - -For the most part, phases should work transparently. By default, a -changeset is created in the draft phase and is moved into the public -phase when it is pushed to another repository. - -Once changesets become public, extensions like mq and rebase will -refuse to operate on them to prevent creating duplicate changesets. -Phases can also be manually manipulated with the :hg:`phase` command -if needed. See :hg:`help -v phase` for examples. - -Phases and servers -================== - -Normally, all servers are ``publishing`` by default. This means:: - - - all draft changesets that are pulled or cloned appear in phase - public on the client - - - all draft changesets that are pushed appear as public on both - client and server - - - secret changesets are neither pushed, pulled, or cloned - -.. note:: - Pulling a draft changeset from a publishing server does not mark it - as public on the server side due to the read-only nature of pull. - -Sometimes it may be desirable to push and pull changesets in the draft -phase to share unfinished work. This can be done by setting a -repository to disable publishing in its configuration file:: - - [phases] - publish = False - -See :hg:`help config` for more information on config files. - -.. note:: - Servers running older versions of Mercurial are treated as - publishing. - -Examples -======== - - - list changesets in draft or secret phase:: - - hg log -r "not public()" - - - change all secret changesets to draft:: - - hg phase --draft "secret()" - - - forcibly move the current changeset and descendants from public to draft:: - - hg phase --force --draft . - - - show a list of changeset revision and phase:: - - hg log --template "{rev} {phase}\n" - - - resynchronize draft changesets relative to a remote repository:: - - hg phase -fd 'outgoing(URL)' - -See :hg:`help phase` for more information on manually manipulating phases. diff --git a/mercurial/help/revisions.txt b/mercurial/help/revisions.txt index f0c2cb2..309f8e2 100644 --- a/mercurial/help/revisions.txt +++ b/mercurial/help/revisions.txt @@ -12,13 +12,13 @@ unique revision identifier and is referred to as a short-form identifier. A short-form identifier is only valid if it is the prefix of exactly one full-length identifier. -Any other string is treated as a bookmark, tag, or branch name. A -bookmark is a movable pointer to a revision. A tag is a permanent name -associated with a revision. A branch name denotes the tipmost revision -of that branch. Bookmark, tag, and branch names must not contain the ":" -character. +Any other string is treated as a tag or branch name. A tag name is a +symbolic name associated with a revision identifier. A branch name +denotes the tipmost revision of that branch. Tag and branch names must +not contain the ":" character. -The reserved name "tip" always identifies the most recent revision. +The reserved name "tip" is a special tag that always identifies the +most recent revision. The reserved name "null" indicates the null revision. This is the revision of an empty repository, and the parent of revision 0. diff --git a/mercurial/help/revsets.txt b/mercurial/help/revsets.txt index 6511668..48838c3 100644 --- a/mercurial/help/revsets.txt +++ b/mercurial/help/revsets.txt @@ -4,9 +4,10 @@ revisions. The language supports a number of predicates which are joined by infix operators. Parenthesis can be used for grouping. -Identifiers such as branch names may need quoting with single or -double quotes if they contain characters like ``-`` or if they match -one of the predefined predicates. +Identifiers such as branch names must be quoted with single or double +quotes if they contain characters outside of +``[._a-zA-Z0-9\x80-\xff]`` or if they match one of the predefined +predicates. Special characters can be used in quoted identifiers by escaping them, e.g., ``\n`` is interpreted as a newline. To prevent them from being diff --git a/mercurial/help/subrepos.txt b/mercurial/help/subrepos.txt index bf5925a..fb3217d 100644 --- a/mercurial/help/subrepos.txt +++ b/mercurial/help/subrepos.txt @@ -1,38 +1,32 @@ Subrepositories let you nest external repositories or projects into a parent Mercurial repository, and make commands operate on them as a -group. - -Mercurial currently supports Mercurial, Git, and Subversion -subrepositories. +group. External Mercurial and Subversion projects are currently +supported. Subrepositories are made of three components: 1. Nested repository checkouts. They can appear anywhere in the - parent working directory. + parent working directory, and are Mercurial clones or Subversion + checkouts. -2. Nested repository references. They are defined in ``.hgsub``, which - should be placed in the root of working directory, and +2. Nested repository references. They are defined in ``.hgsub`` and tell where the subrepository checkouts come from. Mercurial subrepositories are referenced like: path/to/nested = https://example.com/nested/repo/path - Git and Subversion subrepos are also supported: - - path/to/nested = [git]git://example.com/nested/repo/path - path/to/nested = [svn]https://example.com/nested/trunk/path - where ``path/to/nested`` is the checkout location relatively to the parent Mercurial root, and ``https://example.com/nested/repo/path`` is the source repository path. The source can also reference a - filesystem path. + filesystem path. Subversion repositories are defined with: + + path/to/nested = [svn]https://example.com/nested/trunk/path Note that ``.hgsub`` does not exist by default in Mercurial repositories, you have to create and add it to the parent repository before using subrepositories. -3. Nested repository states. They are defined in ``.hgsubstate``, which - is placed in the root of working directory, and +3. Nested repository states. They are defined in ``.hgsubstate`` and capture whatever information is required to restore the subrepositories to the state they were committed in a parent repository changeset. Mercurial automatically record the nested @@ -43,7 +37,7 @@ Subrepositories are made of three components: Adding a Subrepository -====================== +---------------------- If ``.hgsub`` does not exist, create it and add it to the parent repository. Clone or checkout the external projects where you want it @@ -53,7 +47,7 @@ subrepository is tracked and the next commit will record its state in ``.hgsubstate`` and bind it to the committed changeset. Synchronizing a Subrepository -============================= +----------------------------- Subrepos do not automatically track the latest changeset of their sources. Instead, they are updated to the changeset that corresponds @@ -66,47 +60,41 @@ subrepo at the desired revision, test in the top-level repo, then commit in the parent repository to record the new combination. Deleting a Subrepository -======================== +------------------------ To remove a subrepository from the parent repository, delete its reference from ``.hgsub``, then remove its files. Interaction with Mercurial Commands -=================================== +----------------------------------- :add: add does not recurse in subrepos unless -S/--subrepos is - specified. However, if you specify the full path of a file in a - subrepo, it will be added even without -S/--subrepos specified. - Git and Subversion subrepositories are currently silently + specified. Subversion subrepositories are currently silently ignored. :archive: archive does not recurse in subrepositories unless -S/--subrepos is specified. :commit: commit creates a consistent snapshot of the state of the - entire project and its subrepositories. If any subrepositories - have been modified, Mercurial will abort. Mercurial can be made - to instead commit all modified subrepositories by specifying - -S/--subrepos, or setting "ui.commitsubrepos=True" in a - configuration file (see :hg:`help config`). After there are no - longer any modified subrepositories, it records their state and - finally commits it in the parent repository. + entire project and its subrepositories. It does this by first + attempting to commit all modified subrepositories, then recording + their state and finally committing it in the parent + repository. Mercurial can be made to abort if any subrepository + content is modified by setting "ui.commitsubrepos=no" in a + configuration file (see :hg:`help config`). :diff: diff does not recurse in subrepos unless -S/--subrepos is specified. Changes are displayed as usual, on the subrepositories - elements. Git and Subversion subrepositories are currently - silently ignored. - -:forget: forget currently only handles exact file matches in subrepos. - Git and Subversion subrepositories are currently silently ignored. + elements. Subversion subrepositories are currently silently + ignored. :incoming: incoming does not recurse in subrepos unless -S/--subrepos - is specified. Git and Subversion subrepositories are currently - silently ignored. + is specified. Subversion subrepositories are currently silently + ignored. :outgoing: outgoing does not recurse in subrepos unless -S/--subrepos - is specified. Git and Subversion subrepositories are currently - silently ignored. + is specified. Subversion subrepositories are currently silently + ignored. :pull: pull is not recursive since it is not clear what to pull prior to running :hg:`update`. Listing and retrieving all @@ -117,7 +105,7 @@ Interaction with Mercurial Commands :push: Mercurial will automatically push all subrepositories first when the parent repository is being pushed. This ensures new subrepository changes are available when referenced by top-level - repositories. Push is a no-op for Subversion subrepositories. + repositories. :status: status does not recurse into subrepositories unless -S/--subrepos is specified. Subrepository changes are displayed as @@ -132,7 +120,7 @@ Interaction with Mercurial Commands can require network access when using subrepositories. Remapping Subrepositories Sources -================================= +--------------------------------- A subrepository source location may change during a project life, invalidating references stored in the parent repository history. To |