This is an archive of the discontinued Mercurial Phabricator instance.

Differential D1270

help: adding a topic on flags
ClosedPublic

Authored by rdamazio on Oct 31 2017, 12:02 AM.
Tags
None
Subscribers
yuja, durin42, av6 and 3 others

Details

Reviewers
durin42
yuja
Group Reviewers
hg-reviewers
Commits
rHGb0262b25ab48: help: adding a topic on flags
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.

Diff Detail

Repository
rHG Mercurial
Lint
Automatic diff as part of commit; lint not applicable.
Unit
Automatic diff as part of commit; unit tests not applicable.

Event Timeline

rdamazio created this revision.Oct 31 2017, 12:02 AM
martinvonz added a subscriber: martinvonz.Oct 31 2017, 1:17 AM

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.

dlax added a subscriber: dlax.Oct 31 2017, 4:25 AM
dlax added inline comments.
mercurial/help/flags.txt
31

hg help config says that "defaults" are deprecated and that aliases should be used instead.

av6 added a subscriber: av6.Nov 2 2017, 7:43 AM
av6 added inline comments.
mercurial/help/flags.txt
8

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").

36

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`
50

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.

rdamazio marked 4 inline comments as done.Nov 8 2017, 10:29 AM
rdamazio updated this revision to Diff 3334.
rdamazio added a comment.Nov 8 2017, 10:30 AM
In 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.

mercurial/help/flags.txt
8

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.

36

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.

50

--verbose is used to show those flags in hg help, it's not that that flag itself is advanced.

martinvonz added inline comments.Nov 8 2017, 12:52 PM
mercurial/help/flags.txt
9

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

37–40

-ffoo is also valid

68

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.

87

should be committemp here

95

s/simplify/simply/

rdamazio marked 4 inline comments as done.Nov 9 2017, 6:56 AM
rdamazio updated this revision to Diff 3359.
rdamazio marked 4 inline comments as done.Nov 9 2017, 6:57 AM
rdamazio added inline comments.
mercurial/help/flags.txt
68

That's my interpretation of what "hg help commit" says, but if you want me to change it let me know.

durin42 accepted this revision as: durin42.Nov 10 2017, 5:16 PM
durin42 added a subscriber: durin42.

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).

yuja accepted this revision.Nov 13 2017, 8:56 AM
yuja added a subscriber: yuja.

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?

mercurial/help/flags.txt
40

This is wrong. -f=foo is identical to -f =foo.

This revision is now accepted and ready to land.Nov 13 2017, 8:56 AM
Closed by commit rHGb0262b25ab48: help: adding a topic on flags (authored by rdamazio). · Explain WhyNov 13 2017, 9:21 AM
This revision was automatically updated to reflect the committed changes.

Revision Contents
Changeset List

Diff 3445

contrib/wix/help.wxs

<File Name="bundlespec.txt" /> <File Name="bundlespec.txt" />
<File Name="color.txt" /> <File Name="color.txt" />
<File Name="config.txt" KeyPath="yes" /> <File Name="config.txt" KeyPath="yes" />
<File Name="dates.txt" /> <File Name="dates.txt" />
<File Name="diffs.txt" /> <File Name="diffs.txt" />
<File Name="environment.txt" /> <File Name="environment.txt" />
<File Name="extensions.txt" /> <File Name="extensions.txt" />
<File Name="filesets.txt" /> <File Name="filesets.txt" />
<File Name="flags.txt" />
<File Name="glossary.txt" /> <File Name="glossary.txt" />
<File Name="hgignore.txt" /> <File Name="hgignore.txt" />
<File Name="hgweb.txt" /> <File Name="hgweb.txt" />
<File Name="merge-tools.txt" /> <File Name="merge-tools.txt" />
<File Name="pager.txt" /> <File Name="pager.txt" />
<File Name="patterns.txt" /> <File Name="patterns.txt" />
<File Name="phases.txt" /> <File Name="phases.txt" />
<File Name="revisions.txt" /> <File Name="revisions.txt" />

mercurial/help.py

return ''.join(lines) return ''.join(lines)
helptable = sorted([ helptable = sorted([
(['bundlespec'], _("Bundle File Formats"), loaddoc('bundlespec')), (['bundlespec'], _("Bundle File Formats"), loaddoc('bundlespec')),
(['color'], _("Colorizing Outputs"), loaddoc('color')), (['color'], _("Colorizing Outputs"), loaddoc('color')),
(["config", "hgrc"], _("Configuration Files"), loaddoc('config')), (["config", "hgrc"], _("Configuration Files"), loaddoc('config')),
(["dates"], _("Date Formats"), loaddoc('dates')), (["dates"], _("Date Formats"), loaddoc('dates')),
(["flags"], _("Command-line flags"), loaddoc('flags')),
(["patterns"], _("File Name Patterns"), loaddoc('patterns')), (["patterns"], _("File Name Patterns"), loaddoc('patterns')),
(['environment', 'env'], _('Environment Variables'), (['environment', 'env'], _('Environment Variables'),
loaddoc('environment')), loaddoc('environment')),
(['revisions', 'revs', 'revsets', 'revset', 'multirevs', 'mrevs'], (['revisions', 'revs', 'revsets', 'revset', 'multirevs', 'mrevs'],
_('Specifying Revisions'), loaddoc('revisions')), _('Specifying Revisions'), loaddoc('revisions')),
(['filesets', 'fileset'], _("Specifying File Sets"), loaddoc('filesets')), (['filesets', 'fileset'], _("Specifying File Sets"), loaddoc('filesets')),
(['diffs'], _('Diff Formats'), loaddoc('diffs')), (['diffs'], _('Diff Formats'), loaddoc('diffs')),
(['merge-tools', 'mergetools', 'mergetool'], _('Merge Tools'), (['merge-tools', 'mergetools', 'mergetool'], _('Merge Tools'),

mercurial/help/flags.txt

  • This file was added.
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
av6Unsubmitted
Done

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").

av6: This "lists of strings" caught my attention, but it took me some time to figure out what's the…
rdamazioAuthorUnsubmitted
Done

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.

rdamazio: That's the whole point of the "Specifying list flags" section below, and in fact what motivated…
after the command.
martinvonzUnsubmitted
Done

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

martinvonz: The final "and can be specified" sounds a little truncated. Was there supposed to be something…
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
dlaxUnsubmitted
Done

hg help config says that "defaults" are deprecated and that aliases should be used instead.

dlax: `hg help config` says that "defaults" are deprecated and that aliases should be used instead.
======================
The following syntaxes are allowed, assuming a flag 'flagname' with short name
'f'::
av6Unsubmitted
Done

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`
av6: This is a weird-looking macro. Does it work when rendered into e.g. HTML (can be seen hgweb)?
rdamazioAuthorUnsubmitted
Done

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.

rdamazio: Assume that I don't know what I'm doing, as far as the format of this file is concerned :) I…
--flagname=foo
--flagname foo
-f foo
-ffoo
martinvonzUnsubmitted
Done

-ffoo is also valid

martinvonz: `-ffoo` is also valid
yujaUnsubmitted
Not Done

This is wrong. -f=foo is identical to -f =foo.

yuja: This is wrong. -f=foo is identical to -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::
av6Unsubmitted
Done

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.

av6: There are also global flags, they are hidden by default too. I guess you can put them into…
rdamazioAuthorUnsubmitted
Done

--verbose is used to show those flags in hg help, it's not that that flag itself is advanced.

rdamazio: --verbose is used to show those flags in hg help, it's not that that flag itself is advanced.
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
martinvonzUnsubmitted
Done

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.

martinvonz: Do we recommend overriding the command like this or should the left side be called something…
rdamazioAuthorUnsubmitted
Not Done

That's my interpretation of what "hg help commit" says, but if you want me to change it let me know.

rdamazio: That's my interpretation of what "hg help commit" says, but if you want me to change it let me…
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"
martinvonzUnsubmitted
Done

should be committemp here

martinvonz: should be `committemp` here
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.
martinvonzUnsubmitted
Done

s/simplify/simply/

martinvonz: s/simplify/simply/
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

tests/test-globalopts.t

bundlespec Bundle File Formats bundlespec Bundle File Formats
color Colorizing Outputs color Colorizing Outputs
config Configuration Files config Configuration Files
dates Date Formats dates Date Formats
diffs Diff Formats diffs Diff Formats
environment Environment Variables environment Environment Variables
extensions Using Additional Features extensions Using Additional Features
filesets Specifying File Sets filesets Specifying File Sets
flags Command-line flags
glossary Glossary glossary Glossary
hgignore Syntax for Mercurial Ignore Files hgignore Syntax for Mercurial Ignore Files
hgweb Configuring hgweb hgweb Configuring hgweb
internals Technical implementation topics internals Technical implementation topics
merge-tools Merge Tools merge-tools Merge Tools
pager Pager Support pager Pager Support
patterns File Name Patterns patterns File Name Patterns
phases Working with Phases phases Working with Phases
bundlespec Bundle File Formats bundlespec Bundle File Formats
color Colorizing Outputs color Colorizing Outputs
config Configuration Files config Configuration Files
dates Date Formats dates Date Formats
diffs Diff Formats diffs Diff Formats
environment Environment Variables environment Environment Variables
extensions Using Additional Features extensions Using Additional Features
filesets Specifying File Sets filesets Specifying File Sets
flags Command-line flags
glossary Glossary glossary Glossary
hgignore Syntax for Mercurial Ignore Files hgignore Syntax for Mercurial Ignore Files
hgweb Configuring hgweb hgweb Configuring hgweb
internals Technical implementation topics internals Technical implementation topics
merge-tools Merge Tools merge-tools Merge Tools
pager Pager Support pager Pager Support
patterns File Name Patterns patterns File Name Patterns
phases Working with Phases phases Working with Phases

tests/test-help.t

bundlespec Bundle File Formats bundlespec Bundle File Formats
color Colorizing Outputs color Colorizing Outputs
config Configuration Files config Configuration Files
dates Date Formats dates Date Formats
diffs Diff Formats diffs Diff Formats
environment Environment Variables environment Environment Variables
extensions Using Additional Features extensions Using Additional Features
filesets Specifying File Sets filesets Specifying File Sets
flags Command-line flags
glossary Glossary glossary Glossary
hgignore Syntax for Mercurial Ignore Files hgignore Syntax for Mercurial Ignore Files
hgweb Configuring hgweb hgweb Configuring hgweb
internals Technical implementation topics internals Technical implementation topics
merge-tools Merge Tools merge-tools Merge Tools
pager Pager Support pager Pager Support
patterns File Name Patterns patterns File Name Patterns
phases Working with Phases phases Working with Phases
bundlespec Bundle File Formats bundlespec Bundle File Formats
color Colorizing Outputs color Colorizing Outputs
config Configuration Files config Configuration Files
dates Date Formats dates Date Formats
diffs Diff Formats diffs Diff Formats
environment Environment Variables environment Environment Variables
extensions Using Additional Features extensions Using Additional Features
filesets Specifying File Sets filesets Specifying File Sets
flags Command-line flags
glossary Glossary glossary Glossary
hgignore Syntax for Mercurial Ignore Files hgignore Syntax for Mercurial Ignore Files
hgweb Configuring hgweb hgweb Configuring hgweb
internals Technical implementation topics internals Technical implementation topics
merge-tools Merge Tools merge-tools Merge Tools
pager Pager Support pager Pager Support
patterns File Name Patterns patterns File Name Patterns
phases Working with Phases phases Working with Phases
bundlespec Bundle File Formats bundlespec Bundle File Formats
color Colorizing Outputs color Colorizing Outputs
config Configuration Files config Configuration Files
dates Date Formats dates Date Formats
diffs Diff Formats diffs Diff Formats
environment Environment Variables environment Environment Variables
extensions Using Additional Features extensions Using Additional Features
filesets Specifying File Sets filesets Specifying File Sets
flags Command-line flags
glossary Glossary glossary Glossary
hgignore Syntax for Mercurial Ignore Files hgignore Syntax for Mercurial Ignore Files
hgweb Configuring hgweb hgweb Configuring hgweb
internals Technical implementation topics internals Technical implementation topics
merge-tools Merge Tools merge-tools Merge Tools
pager Pager Support pager Pager Support
patterns File Name Patterns patterns File Name Patterns
phases Working with Phases phases Working with Phases
<tr><td> <tr><td>
<a href="/help/filesets"> <a href="/help/filesets">
filesets filesets
</a> </a>
</td><td> </td><td>
Specifying File Sets Specifying File Sets
</td></tr> </td></tr>
<tr><td> <tr><td>
<a href="/help/flags">
flags
</a>
</td><td>
Command-line flags
</td></tr>
<tr><td>
<a href="/help/glossary"> <a href="/help/glossary">
glossary glossary
</a> </a>
</td><td> </td><td>
Glossary Glossary
</td></tr> </td></tr>
<tr><td> <tr><td>
<a href="/help/hgignore"> <a href="/help/hgignore">

tests/test-hgweb-json.t

"summary": "Using Additional Features", "summary": "Using Additional Features",
"topic": "extensions" "topic": "extensions"
}, },
{ {
"summary": "Specifying File Sets", "summary": "Specifying File Sets",
"topic": "filesets" "topic": "filesets"
}, },
{ {
"summary": "Command-line flags",
"topic": "flags"
},
{
"summary": "Glossary", "summary": "Glossary",
"topic": "glossary" "topic": "glossary"
}, },
{ {
"summary": "Syntax for Mercurial Ignore Files", "summary": "Syntax for Mercurial Ignore Files",
"topic": "hgignore" "topic": "hgignore"
}, },
{ {