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 _______________________________________________ Mercurial-devel mailing list Mercurial-devel@mercurial-scm.org https://www.mercurial-scm.org/mailman/listinfo/mercurial-devel