Add an 'advanced' parameter to registering options

Review Request #1739 - Created Feb. 8, 2015 and submitted

Eric Ayers
areitz, benjyw, jsirois, lahosken

Advanced options to not normally display with help messages. They are usually
intended to be set for the entire repo in pants.ini and shouldn't be specified
on the command line because they are difficult to configure or may affect
the hermeticity of the build.

Tagged --target and --source as advanced options, since changing the --source argument
changes what the javac compiler will accept and affects the compiler output.

Added unit test for PantsHelpFormatter change

./pants --help-all
output of --target and --source for is suppressed

./pants --help-all --help-advanced
./pants compile foo --help --help-advanced
output of --target and --source display as follows:

                          Provide source compatibility with this release.
                          (default: 6)
                          Generate class files for this JVM version. (default:


  • 2
  • 1
  • 0
  • 3
Description From Last Updated
What I meant in my previous comment about implementing this in was to just add --help-advanced to the _HELP_FLAGS, ... Benjy Weinberger Benjy Weinberger
We don't need this flag registration any more, right? Benjy Weinberger Benjy Weinberger
Eric Ayers
Eric Ayers
Andy Reitz
Benjy Weinberger
Eric Ayers
John Sirois
Eric Ayers
Review request changed

Status: Closed (submitted)

Change Summary:

Thanks for the reviews. commit 97f4fe4

Benjy Weinberger

src/python/pants/option/ (Diff revision 5)
What I meant in my previous comment about implementing this in was to just add --help-advanced to the _HELP_FLAGS, and then check which help flag was specified in the two places where we use _HELP_FLAGS.

This would allow specifying --help-advanced in task scope, which I'm not sure you can in your current implementation? 

Then you also won't need to register --help-advanced in

Plus, right now if I specify --help-advanced but not --help, is_help is False, which is odd.

In fact, for uniformity I might even add --help-all to _HELP_FLAGS, and check for help-all and help-advanced as the scope name.

Does that make sense?
  1. This does work in task scope because its a global flag. It seems right to model this as a global flag because the effect on the PantsHelpFormatter is global.

    Unfortunately, it did not work to add to _HELP_FLAGS like you suggest because 'help' is a scope. and getes consumed in the while scope: loop above. You can't do option.get_scope('help').advanced either because of the special treatment given to scope 'help'

  2. I do concur with Benjy on one point, it took me awhile to figure out how to get --help-advanced to work. After adding advanced=True to my new option in publish, this was the incantation that showed it to me:

    ./pants publish --help --help-advanced

    I think this is okay for now, but it would be great if sometime in the future specifying --help-advanced implied --help.

  3. help can be a scope but doesn't have to be. We allow it so that ./pants help does the right thing. These are all equivalent:

    ./pants help ./pants -h ./pants --help

    My point about having that flag work in task scope was to allow this:

    ./pants compile --help-advanced

    Where currently I guess you'd need:

    ./pants --help-advanced compile --help

    Which seems clunky?

    I think at least one of us is not clear on what the other is saying. Let me cobble together a quick change just to to either explain what I mean or encounter the obstacle you mention for myself... :)

We don't need this flag registration any more, right?

  1. This is used in that this where the help gets printed from for the --help-advanced argument itself. I could not register it, though and just tack on --help-advanced in the same way that --help-all is processed if you prefer. Or we could modify --help-all to be consistent with the change I just made for --help-advanced and register it here.

  2. For clarity, this is what I'm referring to with --help-all help text:

    It just gets pasted on to the end of the help text, not registered as a global option.