D1270: help: adding a topic on flags
This revision was automatically updated to reflect the committed changes.
Closed by commit rHGb0262b25ab48: help: adding a topic on flags (authored by
rdamazio, committed by ).
CHANGED PRIOR TO COMMIT
https://phab.mercurial-scm.org/D1270?vs=3359=3445#toc
REPOSITORY
rHG Mercurial
CHANGES SINCE LAST UPDATE
https://phab.mercurial-scm.org/D1270?vs=3359=3445
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
extensionsUsing 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
extensionsUsing 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
extensionsUsing 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
+
+ flags
+
+
+ Command-line flags
+
+
glossary
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
extensionsUsing 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
extensionsUsing 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,104 @@
+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
+-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
D1270: help: adding a topic on flags
yuja accepted this revision. yuja added a comment. This revision is now accepted and ready to land. Removed -f=foo and queued, thanks. > it makes permanent my --no- boolean prefix for flags, Perhaps we can add some note saying --no- is still experimental? INLINE COMMENTS > flags.txt:39 > +--flagname foo > +-f=foo > +-f foo This is wrong. -f=foo is identical to -f =foo. REPOSITORY rHG Mercurial REVISION DETAIL https://phab.mercurial-scm.org/D1270 To: rdamazio, #hg-reviewers, durin42, yuja Cc: yuja, durin42, av6, dlax, martinvonz, mercurial-devel ___ Mercurial-devel mailing list Mercurial-devel@mercurial-scm.org https://www.mercurial-scm.org/mailman/listinfo/mercurial-devel
D1270: help: adding a topic on flags
durin42 accepted this revision as: durin42. durin42 added a comment. I'm +1 on this, but won't accept as a reviewer since I've got at least two biases here (it makes permanent my --no- boolean prefix for flags, and it'll solve some support problems at G). REPOSITORY rHG Mercurial REVISION DETAIL https://phab.mercurial-scm.org/D1270 To: rdamazio, #hg-reviewers, durin42 Cc: durin42, av6, dlax, martinvonz, mercurial-devel ___ Mercurial-devel mailing list Mercurial-devel@mercurial-scm.org https://www.mercurial-scm.org/mailman/listinfo/mercurial-devel
D1270: help: adding a topic on flags
rdamazio marked 4 inline comments as done. rdamazio added inline comments. INLINE COMMENTS > martinvonz wrote in flags.txt:67 > Do we recommend overriding the command like this or should the left side be > called something else (maybe "icommit")? I really don't know what we > recommend here, so don't take my question to imply that you shouldn't do it > the way you have done it. That's my interpretation of what "hg help commit" says, but if you want me to change it let me know. REPOSITORY rHG Mercurial REVISION DETAIL https://phab.mercurial-scm.org/D1270 To: rdamazio, #hg-reviewers Cc: av6, dlax, martinvonz, mercurial-devel ___ Mercurial-devel mailing list Mercurial-devel@mercurial-scm.org https://www.mercurial-scm.org/mailman/listinfo/mercurial-devel
D1270: help: adding a topic on flags
rdamazio updated this revision to Diff 3359.
rdamazio marked 4 inline comments as done.
REPOSITORY
rHG Mercurial
CHANGES SINCE LAST UPDATE
https://phab.mercurial-scm.org/D1270?vs=3334=3359
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
extensionsUsing 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
extensionsUsing 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
extensionsUsing 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
+
+ flags
+
+
+ Command-line flags
+
+
glossary
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
extensionsUsing 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
extensionsUsing 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,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
D1270: help: adding a topic on flags
martinvonz added inline comments. INLINE COMMENTS > flags.txt:8 > +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. > + The final "and can be specified" sounds a little truncated. Was there supposed to be something after? Or maybe it's no longer needed since you already said "can be used with any command"? > flags.txt:36-39 > +--flagname=foo > +--flagname foo > +-f=foo > +-f foo `-ffoo` is also valid > flags.txt:67 > +[alias] > +commit = commit --interactive > + Do we recommend overriding the command like this or should the left side be called something else (maybe "icommit")? I really don't know what we recommend here, so don't take my question to imply that you shouldn't do it the way you have done it. > flags.txt:86 > + > +hg commit -m "Used value" > + should be `committemp` here > flags.txt:94 > +as described above. > +Except for list flags, defaults can be overridden on the command line > simplify > +by specifying the flag in that location. s/simplify/simply/ REPOSITORY rHG Mercurial REVISION DETAIL https://phab.mercurial-scm.org/D1270 To: rdamazio, #hg-reviewers Cc: av6, dlax, martinvonz, mercurial-devel ___ Mercurial-devel mailing list Mercurial-devel@mercurial-scm.org https://www.mercurial-scm.org/mailman/listinfo/mercurial-devel
D1270: help: adding a topic on flags
rdamazio updated this revision to Diff 3334.
rdamazio marked 4 inline comments as done.
REPOSITORY
rHG Mercurial
CHANGES SINCE LAST UPDATE
https://phab.mercurial-scm.org/D1270?vs=3168=3334
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
extensionsUsing 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
extensionsUsing 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
extensionsUsing 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
+
+ flags
+
+
+ Command-line flags
+
+
glossary
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
extensionsUsing 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
extensionsUsing 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,105 @@
+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.
+
+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
+
+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
D1270: help: adding a topic on flags
rdamazio added a comment. In https://phab.mercurial-scm.org/D1270#21058, @martinvonz wrote: > We're in code freeze for approximately two more days, so this will have to wait until ~Thursday. Still, thanks for the patch. I'm happy to include something like this. Things that struck me as missing: > > 1. Long vs short form (that e.g. "--verbose" and "-v" are equivalent if the refer to the same flag, which they do) > 2. Non-list, non-boolean flags that take arguments, such as "--rev", and that "--rev=tip", "--rev tip", "-r=tip", "-r tip", and "-rtip" are equivalent > 3. Short flags can be combined: "-pvr tip" is valid > 4. Later flags override earlier flags > > We don't necessarily have to include all that in the first patch. Tried to address all of these. INLINE COMMENTS > av6 wrote in flags.txt:7 > This "lists of strings" caught my attention, but it took me some time to > figure out what's the matter. I don't feel strongly, but here are some points: > > 1. it's not clear what a "list of strings" is and how to specify it: is it a > comma-separated list? > 2. it's not a type that //one// command-line flag can take (i.e. no > `--flag=foo,bar` or anything), you must use multiple flags on command line to > build this list, so it's unlike the 3 previous types > 3. I don't think we have anywhere (in the code) a list of integers or > booleans right now, but nothing prevents this in future, or in an extension > > I think this data type is a result of looking at the internals that allow > some python variables (associated with handling command line flags in the > code) to be lists, but because our CLI is not python, this phrase is more > distracting than helpful. I think taking the note that's in `hg help` and > explaining it is better: "[+] can be repeated" (essentially merging > "​Specifying list flags" and "Overriding flag defaults"). That's the whole point of the "Specifying list flags" section below, and in fact what motivated me to send this patch. I don't think the code supports parsing a list as numbers or booleans, right now. > av6 wrote in flags.txt:35 > This is a weird-looking macro. Does it work when rendered into e.g. HTML (can > be seen hgweb)? I've only seen this format: > > :hg:`help config` Assume that I don't know what I'm doing, as far as the format of this file is concerned :) I just tried hgweb and fixed a few things. > av6 wrote in flags.txt:49 > There are also global flags, they are hidden by default too. I guess you can > put them into these 3 categories, but I don't think of --quiet or --verbose > as advanced (much less experimental or deprecated). Just a nitpick. --verbose is used to show those flags in hg help, it's not that that flag itself is advanced. REPOSITORY rHG Mercurial REVISION DETAIL https://phab.mercurial-scm.org/D1270 To: rdamazio, #hg-reviewers Cc: av6, dlax, martinvonz, mercurial-devel ___ Mercurial-devel mailing list Mercurial-devel@mercurial-scm.org https://www.mercurial-scm.org/mailman/listinfo/mercurial-devel
D1270: help: adding a topic on flags
av6 added inline comments. INLINE COMMENTS > flags.txt:7 > +Mercurial command-line flags can be strings, numbers, booleans, or lists of > +strings. > + This "lists of strings" caught my attention, but it took me some time to figure out what's the matter. I don't feel strongly, but here are some points: 1. it's not clear what a "list of strings" is and how to specify it: is it a comma-separated list? 2. it's not a type that //one// command-line flag can take (i.e. no `--flag=foo,bar` or anything), you must use multiple flags on command line to build this list, so it's unlike the 3 previous types 3. I don't think we have anywhere (in the code) a list of integers or booleans right now, but nothing prevents this in future, or in an extension I think this data type is a result of looking at the internals that allow some python variables (associated with handling command line flags in the code) to be lists, but because our CLI is not python, this phrase is more distracting than helpful. I think taking the note that's in `hg help` and explaining it is better: "[+] can be repeated" (essentially merging "​Specifying list flags" and "Overriding flag defaults"). > flags.txt:35 > + > +For more information on hgrc files, see :hg:help:config. > + This is a weird-looking macro. Does it work when rendered into e.g. HTML (can be seen hgweb)? I've only seen this format: :hg:`help config` > flags.txt:49 > +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:: There are also global flags, they are hidden by default too. I guess you can put them into these 3 categories, but I don't think of --quiet or --verbose as advanced (much less experimental or deprecated). Just a nitpick. REPOSITORY rHG Mercurial REVISION DETAIL https://phab.mercurial-scm.org/D1270 To: rdamazio, #hg-reviewers Cc: av6, dlax, martinvonz, mercurial-devel ___ Mercurial-devel mailing list Mercurial-devel@mercurial-scm.org https://www.mercurial-scm.org/mailman/listinfo/mercurial-devel
D1270: help: adding a topic on flags
dlax added inline comments. INLINE COMMENTS > flags.txt:30 > +In order to set a default value for a flag in an hgrc file, set it under the > +[defaults] section of the hgrc file:: > + `hg help config` says that "defaults" are deprecated and that aliases should be used instead. REPOSITORY rHG Mercurial REVISION DETAIL https://phab.mercurial-scm.org/D1270 To: rdamazio, #hg-reviewers Cc: dlax, martinvonz, mercurial-devel ___ Mercurial-devel mailing list Mercurial-devel@mercurial-scm.org https://www.mercurial-scm.org/mailman/listinfo/mercurial-devel
D1270: help: adding a topic on flags
martinvonz added a comment. We're in code freeze for approximately two more days, so this will have to wait until ~Thursday. Still, thanks for the patch. I'm happy to include something like this. Things that struck me as missing: 1. Long vs short form (that e.g. "--verbose" and "-v" are equivalent if the refer to the same flag, which they do) 2. Non-list, non-boolean flags that take arguments, such as "--rev", and that "--rev=tip", "--rev tip", "-r=tip", "-r tip", and "-rtip" are equivalent 3. Short flags can be combined: "-pvr tip" is valid 4. Later flags override earlier flags We don't necessarily have to include all that in the first patch. REPOSITORY rHG Mercurial REVISION DETAIL https://phab.mercurial-scm.org/D1270 To: rdamazio, #hg-reviewers Cc: martinvonz, mercurial-devel ___ Mercurial-devel mailing list Mercurial-devel@mercurial-scm.org https://www.mercurial-scm.org/mailman/listinfo/mercurial-devel
D1270: help: adding a topic on flags
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
extensionsUsing 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
extensionsUsing 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
extensionsUsing 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
+
+ flags
+
+
+ Command-line flags
+
+
glossary
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
extensionsUsing 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
extensionsUsing 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
