Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Include mutually exclusive flags in help text #1863

Merged
merged 7 commits into from
Feb 12, 2024

Conversation

joshfrench
Copy link
Contributor

@joshfrench joshfrench commented Feb 4, 2024

What type of PR is this?

  • feature

What this PR does / why we need it:

The default help text did not include mutually exclusive flags; now it does:

cmd := &cli.Command{
		MutuallyExclusiveFlags: []cli.MutuallyExclusiveFlags{{
			Flags: [][]cli.Flag{
				{
					&cli.StringFlag{
						Name: "foo",
					},
				},
				{
					&cli.BoolFlag{
						Name:     "bar",
						Category: "Category",
					},
				},
				{
					&cli.BoolFlag{
						Name:     "baz",
						Category: "Category",
					},
				},
			},
		}},
	}
GLOBAL OPTIONS:
   --foo value
   --help, -h   show help (default: false)

   Category

   --bar  (default: false)
   --baz  (default: false)

Changes:

  • SetCategory method added to Flag interface.
  • Category field and propagateCategory method added to MutuallyExclusiveFlags, allowing mutex group to set a category and propagate it downward to all flags within.
  • Mutex group category downward-propagation added to command and subcommand setup, prior to computing visible categories. This implies that any category set on a mutex flag itself will be ignored if no group category is set, or overridden if one is.
  • Replaced cmd.Flags with cmd.allFlags() when calculating visible flags and visible flag categories, to ensure downward-propagated group categories are included in help text.

Which issue(s) this PR fixes:

Fixes #1858

Special notes for your reviewer:

I considered two approaches, described in #1858 . This is the simpler of the two, where no attempt is made to display or categorize mutually exclusive flags in any special way. Under this approach the changes are minimal and users don't need to consider any special cases when using mutually exclusive flags. Flags within a mutex group now ignore their own Category and inherit it from the group instead, but there's precedent with the mutex group's Required field so it's not an entirely new concept.

Testing

Unit tests are updated to reflect both uncategorized and categorized output.

Release Notes

Mutually exclusive flags are now included in the default help text.

@joshfrench
Copy link
Contributor Author

@dearchap I'm stalled at the following test error:

# 🚨 ---> Hey! <---
# The unified diff above indicates that the public API surface area
# has changed. If you feel that the changes are acceptable for the
# v3.x series, please run the following command to promote the
# current go docs:
#
#     make v3approve

Should I run that and get the tests passing, or would you like to review the changes first? Thanks!

@dearchap
Copy link
Contributor

@joshfrench Yes the changes look good for the most part. Can you run make v3approve and push ?

@joshfrench
Copy link
Contributor Author

@dearchap pushed!

@dearchap dearchap merged commit 204d34f into urfave:main Feb 12, 2024
11 of 12 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

v3 MutuallyExclusive flags are not included in help text
2 participants