D1270: help: adding a topic on flags
rdamazio (Rodrigo Damazio Bovendorp)
phabricator at mercurial-scm.org
Tue Oct 31 04:02:22 UTC 2017
rdamazio created this revision.
Herald added a subscriber: mercurial-devel.
Herald added a reviewer: hg-reviewers.
REVISION SUMMARY
This is a short topic to explain how command-line flags can be specified.
Some users have been confused by hg offerring different flag syntax than some
other libraries, so it'd be nice to point them to this rather than explaining
it every time.
REPOSITORY
rHG Mercurial
REVISION DETAIL
https://phab.mercurial-scm.org/D1270
AFFECTED FILES
contrib/wix/help.wxs
mercurial/help.py
mercurial/help/flags.txt
tests/test-globalopts.t
tests/test-help.t
tests/test-hgweb-json.t
CHANGE DETAILS
diff --git a/tests/test-hgweb-json.t b/tests/test-hgweb-json.t
--- a/tests/test-hgweb-json.t
+++ b/tests/test-hgweb-json.t
@@ -1581,6 +1581,10 @@
"topic": "filesets"
},
{
+ "summary": "Command-line flags",
+ "topic": "flags"
+ },
+ {
"summary": "Glossary",
"topic": "glossary"
},
diff --git a/tests/test-help.t b/tests/test-help.t
--- a/tests/test-help.t
+++ b/tests/test-help.t
@@ -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
@@ -2010,6 +2013,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>
diff --git a/tests/test-globalopts.t b/tests/test-globalopts.t
--- a/tests/test-globalopts.t
+++ b/tests/test-globalopts.t
@@ -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
diff --git a/mercurial/help/flags.txt b/mercurial/help/flags.txt
new file mode 100644
--- /dev/null
+++ b/mercurial/help/flags.txt
@@ -0,0 +1,53 @@
+Most Mercurial commands accept various flags.
+
+Flag types
+==========
+
+Mercurial command-line flags can be strings, numbers, booleans, or lists of
+strings.
+
+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, set it under the
+[defaults] section of the hgrc file::
+
+ [defaults]
+ commit = --interactive
+
+For more information on hgrc files, see :hg:help:config.
+
+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 simplify
+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
+
diff --git a/mercurial/help.py b/mercurial/help.py
--- a/mercurial/help.py
+++ b/mercurial/help.py
@@ -224,6 +224,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')),
diff --git a/contrib/wix/help.wxs b/contrib/wix/help.wxs
--- a/contrib/wix/help.wxs
+++ b/contrib/wix/help.wxs
@@ -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" />
To: rdamazio, #hg-reviewers
Cc: mercurial-devel
More information about the Mercurial-devel
mailing list