Patchwork D1270: help: adding a topic on flags

login
register
mail settings
Submitter phabricator
Date Oct. 31, 2017, 4:02 a.m.
Message ID <differential-rev-PHID-DREV-ddg5igmggn3b7spydlmv-req@phab.mercurial-scm.org>
Download mbox | patch
Permalink /patch/25314/
State Superseded
Headers show

Comments

phabricator - Oct. 31, 2017, 4:02 a.m.
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




To: rdamazio, #hg-reviewers
Cc: mercurial-devel
phabricator - Oct. 31, 2017, 5:17 a.m.
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
phabricator - Oct. 31, 2017, 8:25 a.m.
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
phabricator - Nov. 8, 2017, 5:52 p.m.
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
phabricator - Nov. 9, 2017, 11:57 a.m.
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
phabricator - Nov. 10, 2017, 10:16 p.m.
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
phabricator - Nov. 13, 2017, 1:56 p.m.
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

Patch

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" />