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 @@ + diff --git a/mercurial/help.py b/mercurial/help.py --- a/mercurial/help.py +++ b/mercurial/help.py @@ -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')), 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 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 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/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 @@ -2013,6 +2016,13 @@ Specifying File Sets + + flags + + + Command-line flags + + glossary 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" },