@@ -1581,6 +1581,10 @@
"topic": "filesets"
},
{
+ "summary": "Command-line flags",
+ "topic": "flags"
+ },
+ {
"summary": "Glossary",
"topic": "glossary"
},
@@ -110,6 +110,7 @@
environment Environment Variables
extensions Using Additional Features
filesets Specifying File Sets
+ flags Command-line flags
glossary Glossary
hgignore Syntax for Mercurial Ignore Files
hgweb Configuring hgweb
@@ -188,6 +189,7 @@
environment Environment Variables
extensions Using Additional Features
filesets Specifying File Sets
+ flags Command-line flags
glossary Glossary
hgignore Syntax for Mercurial Ignore Files
hgweb Configuring hgweb
@@ -865,6 +867,7 @@
environment Environment Variables
extensions Using Additional Features
filesets Specifying File Sets
+ flags Command-line flags
glossary Glossary
hgignore Syntax for Mercurial Ignore Files
hgweb Configuring hgweb
@@ -2013,6 +2016,13 @@
Specifying File Sets
</td></tr>
<tr><td>
+ <a href="/help/flags">
+ flags
+ </a>
+ </td><td>
+ Command-line flags
+ </td></tr>
+ <tr><td>
<a href="/help/glossary">
glossary
</a>
@@ -355,6 +355,7 @@
environment Environment Variables
extensions Using Additional Features
filesets Specifying File Sets
+ flags Command-line flags
glossary Glossary
hgignore Syntax for Mercurial Ignore Files
hgweb Configuring hgweb
@@ -439,6 +440,7 @@
environment Environment Variables
extensions Using Additional Features
filesets Specifying File Sets
+ flags Command-line flags
glossary Glossary
hgignore Syntax for Mercurial Ignore Files
hgweb Configuring hgweb
new file mode 100644
@@ -0,0 +1,107 @@
+Most Mercurial commands accept various flags.
+
+Flag names
+==========
+
+Flags for each command are listed in :hg:`help` for that command.
+Additionally, some flags, such as --repository, are global and can be used with
+any command - those are seen in :hg:`help -v`, and can be specified before or
+after the command.
+
+Every flag has at least a long name, such as --repository. Some flags may also
+have a short one-letter name, such as the equivalent -R. Using the short or long
+name is equivalent and has the same effect.
+
+Flags that have a short name can also be bundled together - for instance, to
+specify both --edit (short -e) and --interactive (short -i), one could use::
+
+ hg commit -ei
+
+If any of the bundled flags takes a value (i.e. is not a boolean), it must be
+last, followed by the value::
+
+ hg commit -im 'Message'
+
+Flag types
+==========
+
+Mercurial command-line flags can be strings, numbers, booleans, or lists of
+strings.
+
+Specifying flag values
+======================
+
+The following syntaxes are allowed, assuming a flag 'flagname' with short name
+'f'::
+
+ --flagname=foo
+ --flagname foo
+ -f=foo
+ -f foo
+ -ffoo
+
+This syntax applies to all non-boolean flags (strings, numbers or lists).
+
+Specifying boolean flags
+========================
+
+Boolean flags do not take a value parameter. To specify a boolean, use the flag
+name to set it to true, or the same name prefixed with 'no-' to set it to
+false::
+
+ hg commit --interactive
+ hg commit --no-interactive
+
+Specifying list flags
+=====================
+
+List flags take multiple values. To specify them, pass the flag multiple times::
+
+ hg files --include mercurial --include tests
+
+Setting flag defaults
+=====================
+
+In order to set a default value for a flag in an hgrc file, it is recommended to
+use aliases::
+
+ [alias]
+ commit = commit --interactive
+
+For more information on hgrc files, see :hg:`help config`.
+
+Overriding flags on the command line
+====================================
+
+If the same non-list flag is specified multiple times on the command line, the
+latest specification is used::
+
+ hg commit -m "Ignored value" -m "Used value"
+
+This includes the use of aliases - e.g., if one has::
+
+ [alias]
+ committemp = commit -m "Ignored value"
+
+then the following command will override that -m::
+
+ hg committemp -m "Used value"
+
+
+Overriding flag defaults
+========================
+
+Every flag has a default value, and you may also set your own defaults in hgrc
+as described above.
+Except for list flags, defaults can be overridden on the command line simply by
+specifying the flag in that location.
+
+Hidden flags
+============
+
+Some flags are not shown in a command's help by default - specifically, those
+that are deemed to be experimental, deprecated or advanced. To show all flags,
+add the --verbose flag for the help command::
+
+ hg help --verbose commit
+
@@ -226,6 +226,7 @@
(['color'], _("Colorizing Outputs"), loaddoc('color')),
(["config", "hgrc"], _("Configuration Files"), loaddoc('config')),
(["dates"], _("Date Formats"), loaddoc('dates')),
+ (["flags"], _("Command-line flags"), loaddoc('flags')),
(["patterns"], _("File Name Patterns"), loaddoc('patterns')),
(['environment', 'env'], _('Environment Variables'),
loaddoc('environment')),
@@ -23,6 +23,7 @@
<File Name="environment.txt" />
<File Name="extensions.txt" />
<File Name="filesets.txt" />
+ <File Name="flags.txt" />
<File Name="glossary.txt" />
<File Name="hgignore.txt" />
<File Name="hgweb.txt" />