How to filter stacks is unclear

[pbrisbin]

Users seem to expect [STACK_NAME..] arguments to commands as the way you limit processing to those stacks.

This is reasonable, but we don't do it that way for a few of reasons:

1. Arguments at the end of sub-commands need to be implemented individually for those sub-commands; since filtering applies to everything, we chose to implement a global option instead. I'll admit, I do not know how global arguments work.
2. The most common use-case for this filtering is on CI, filtering to changed stacks. In that context, producing a comma-separated list (--filter=a,b,c is easier than multiple positional options (--filter a --filter b --filter c). I also find it makes the OR nature more apparent.
3. Wanting to deploy things in a group ("all prod stacks", "all memcached stacks", etc) is common too, so we support globs

All of this together has resulted in the current option:

stackctl --filter 'prod/*' deploy

stackctl --filter 'iam.yaml,apps/*/iam.yaml' cat

We should do two things to clarify this:

1- Add EXAMPLES to (at least) stackctl.1 that show how to use --filter

This may be happening in #104, so we should include this there.

2- Ensure that global options appear in sub-command --help output.

Today,

% stackctl deploy --help
Usage: stackctl deploy [-p|--parameter KEY=[VALUE]] [-t|--tag KEY=[VALUE]]
                       [--save-change-sets DIRECTORY] [--no-confirm]
                       [--no-remove] [--clean]

  Deploy specifications

Available options:
  -p,--parameter KEY=[VALUE]
                           Override the given Parameter for this operation
  -t,--tag KEY=[VALUE]     Override the given Tag for this operation
  --save-change-sets DIRECTORY
                           Save executed changesets to DIRECTORY
  --no-confirm             Don't confirm changes before executing
  --no-remove              Don't delete removed Stacks
  --clean                  Remove all changesets from Stack after deploy
  -h,--help                Show this help text

How it should look,

% stackctl deploy --help
Usage: stackctl deploy [-p|--parameter KEY=[VALUE]] [-t|--tag KEY=[VALUE]]
                       [--save-change-sets DIRECTORY] [--no-confirm]
                       [--no-remove] [--clean]

  Deploy specifications

Available options:
  -p,--parameter KEY=[VALUE]
                           Override the given Parameter for this operation
  -t,--tag KEY=[VALUE]     Override the given Tag for this operation
  --save-change-sets DIRECTORY
                           Save executed changesets to DIRECTORY
  --no-confirm             Don't confirm changes before executing
  --no-remove              Don't delete removed Stacks
  --clean                  Remove all changesets from Stack after deploy
  -h,--help                Show this help text

Global options:
  -d,--directory PATH      Operate on specifications in PATH
  --filter PATTERN[,PATTERN]
                           Filter specifications to match PATTERN(s)
  --color auto|always|never
                           When to colorize output
  -v,--verbose             Increase verbosity (can be passed multiple times)
  --auto-sso WHEN          Automatically run aws-sso-login if necessary?

I think we simply need to use the helpShowGlobals modifier, as per docs:

Global options are off by default, to enable them, use
the helpShowGlobals modifier.

[chris-martin]

I think if I first read this doc, knowing the correct directory to run stackctl from, the first thing I would try to deploy stacks/539282909833.freckle-dev/us-east-1/dev would be

stackctl deploy --directory stacks/539282909833.freckle-dev/us-east-1/dev

[pbrisbin]

And now that you know that is wrong, what could the doc have said to have guided you correctly?

[chris-martin]

Maybe it would help to establish a term for the root directory, e.g. the "stack collection".

% stackctl deploy --help
Usage: stackctl deploy [-p|--parameter KEY=[VALUE]] [-t|--tag KEY=[VALUE]]
                       [--save-change-sets DIRECTORY] [--no-confirm]
                       [--no-remove] [--clean]

  Deploy specifications

  By default, this will deploy the entire stack collection. To deploy a
  specific stack or set of stacks, use the --filter argument to filter
  the collection by file path.

Available options:
  -p,--parameter KEY=[VALUE]
                           Override the given Parameter for this operation
  -t,--tag KEY=[VALUE]     Override the given Tag for this operation
  --save-change-sets DIRECTORY
                           Save executed changesets to DIRECTORY
  --no-confirm             Don't confirm changes before executing
  --no-remove              Don't delete removed Stacks
  --clean                  Remove all changesets from Stack after deploy
  -h,--help                Show this help text

Global options:
  -d,--directory PATH      Use the stack collection located at PATH
                           (default: current working directory)
  --filter PATTERN[,PATTERN]
                           Filter specifications to match PATTERN(s)
  --color auto|always|never
                           When to colorize output
  -v,--verbose             Increase verbosity (can be passed multiple times)
  --auto-sso WHEN          Automatically run aws-sso-login if necessary?

[pbrisbin]

Maybe it would help to establish a term for the root directory

Yes, I agree.

stack collection

That works, I also like "stack specifications tree" (shorted to "spec tree" in context). I think using the term "tree" could help with the intuition about the semantics of the directory tree.

[pbrisbin]

Would you expect to have the footer present (and adjusted) for every sub-command?

By default, this will ?subcommand? the entire stack collection. To ?subcommand? a
specific stack or set of stacks, use the --filter argument to filter
the collection by file path.

I imagine so, it's just annoying to do, so I'm wondering if there's an 80/20, maybe

By default, this will operate on the entire stack collection. To operate on a
specific stack or set of stacks, use the --filter argument to filter
the collection by file path.

Then I can make a constant to just use with each subcommand parser.