CLI woes with stack config set?

[sjakobi]

The --global flag for stack config set is intended to cause configuration changes to apply to ~/.stack/config.yaml instead of the configuration of the current project.

Because resolver like all project configuration options cannot be configured in the global ~/.stack/config.yaml, in #2675 I reimplemented the field names like system-ghc and resolver as subcommands of which only some take the --global flag.

A downside to this approach is that the --global can only be passed in after the field name, so e.g. this command is a syntax error:

~ $ stack config set --global system-ghc true
Invalid option `--global'

Usage: stack config set COMMAND [--help]
  Sets a field in the project's stack.yaml to value

Alternatively, it would be possible to make the --global flag an option to the stack config or stack config set commands, which would make other positions of the flag acceptable, but force the code to handle nonsensical commands like stack config set --global resolver lts elsewhere.

A monadic option parser could allow other positions for the --global while keeping stack config set --global resolver lts a syntax error. optparse-applicative provides some functionality for monadic parsing but it's more difficult to use and more difficult to get a good CLI help text with it.

[Blaisorblade]

Ah, thanks for reminding why --global is nonsensical for some options, I hadn't realized this till now. It would be good to allow other orders and have --global documented in general — from the above example, it's not clear how to discover what you can set. Sorry haven't tested yet.

but force the code to handle nonsensical commands like stack config set --global resolver lts elsewhere.

I suspect that's best for the user—we should just error and explain that the used field is not global. Maybe it should be obvious that resolver can't be global, but nothing is obvious to novices, and other flags are probably more confusing.

When I wrote:

If there's some design reason why --global makes no sense for resolver maybe we should reconsider the (EDIT) command-line API.

my reasoning was that having an option like --global makes sense if it works for all commands (like in git config), otherwise we might want a different CLI. Maybe a stack global-config set if the contents are very different? Not sure what's best.

[sjakobi]

from the above example, it's not clear how to discover what you can set

~ $ stack config set --help
Usage: stack config set COMMAND [--help]
  Sets a field in the project's stack.yaml to value

Available options:
  --help                   Show this help text

Available commands:
  resolver                 Change the resolver of the current project. See
                           https://docs.haskellstack.org/en/stable/yaml_configuration/#resolver
                           for more info.
  system-ghc               Configure whether stack should use a system GHC
                           installation or not.
  install-ghc              Configure whether stack should automatically install
                           GHC when necessary.

Run 'stack --help' for global options that apply to all subcommands.
~ $ stack config set system-ghc --help
Usage: stack config set system-ghc [--global] true/false
  Configure whether stack should use a system GHC installation or not.

Available options:
  --global                 Modify the global configuration (typically at
                           "~/.stack/config.yaml") instead of the project
                           stack.yaml.
  -h,--help                Show this help text

but force the code to handle nonsensical commands like stack config set --global resolver lts elsewhere.

I suspect that's best for the user—we should just error and explain that the used field is not global. Maybe it should be obvious that resolver can't be global, but nothing is obvious to novices

I agree.

Maybe a stack global-config set if the contents are very different?

Currently everything that can be configured in ~/.stack/config.yaml can also be configured in stack.yamls (although not everything makes sense). So that's what should be configurable with both commands.

The additional options that should be available from stack config eventually, but not from stack global-config can mostly be gleaned from the fields of the BuildConfig type.

A global-config command could be nice to easily discover from the command line which fields can be set globally`.

[Blaisorblade]

Thanks, I stand corrected on discoverability. The only annoyance is you don't learn about --global till you look at specific commands, and at least I would ignore at first the required location for it.

[sjakobi]

@mgsloan: What do you think about creating a global-config command to replace the hard to discover and easy to misplace --global flag for stack config set?

I think it would also help make it quite clear what options can be configured in a project and which ones are available globally.

[mgsloan]

@sjakobi I think that's a great idea! Worth implementing before the next release.

Putting this on P0 so that we consider this issue before doing the next release.

[mgsloan]

I think the current CLI is fine - the help is available via stack config set system-ghc --help. The main purpose of the global flag is to aid travis CI scripts, and that's documented in https://github.com/commercialhaskell/stack/blob/master/doc/travis_ci.md