This is an archive of the discontinued Mercurial Phabricator instance.

help: adding a topic on flags
ClosedPublic

Authored by rdamazio on Oct 31 2017, 12:02 AM.

Download Raw Diff

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

Lint Skipped

Unit

Unit Tests Skipped

Event Timeline

rdamazio created this revision.Oct 31 2017, 12:02 AM

Herald added a reviewer: hg-reviewers. · View Herald TranscriptOct 31 2017, 12:02 AM

Herald added a subscriber: mercurial-devel. · View Herald Transcript

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:

Long vs short form (that e.g. "--verbose" and "-v" are equivalent if the refer to the same flag, which they do)
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
Short flags can be combined: "-pvr tip" is valid
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: it's not clear what a "list of strings" is and how to specify it: is it a comma-separated list? 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 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.

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:

Long vs short form (that e.g. "--verbose" and "-v" are equivalent if the refer to the same flag, which they do)

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

Short flags can be combined: "-pvr tip" is valid

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.

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

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
39	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

		Path
M		contrib/wix/help.wxs (1 line)
M		mercurial/help.py (1 line)
A	M	mercurial/help/flags.txt (107 lines)
M		tests/test-globalopts.t (2 lines)
M		tests/test-help.t (10 lines)
M		tests/test-hgweb-json.t (4 lines)

Diff	ID	Description	Created	Lint	Unit
Base		Base
Diff 1	3168		Oct 31 2017, 12:02 AM	★	★
Diff 2	3334		Nov 8 2017, 10:29 AM	★	★
Diff 3	3359		Nov 9 2017, 6:56 AM	★	★
Diff 4	3445	rHGb0262b25ab486c896e4376d3a0ad59917254aa2a	Oct 30 2017, 11:35 PM	★	★

Diff 3359

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: it's not clear what a "list of strings" is and how to specify it: is it a comma-separated list? 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 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
				yujaUnsubmitted Not Done This is wrong. -f=foo is identical to -f =foo. yuja: This is wrong. -f=foo is identical to -f =foo.
				-f foo
				martinvonzUnsubmitted Done `-ffoo` is also valid martinvonz: `-ffoo` is also valid
				-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::
				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]
				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…
				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::

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

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"
	},			},
	{			{