From f1a7857ea01bf00d265c27e536e5d053d6c66e2c Mon Sep 17 00:00:00 2001 From: patrick brisbin Date: Fri, 17 Oct 2025 11:33:41 -0400 Subject: [PATCH 1/2] chore(docs): update --directory help text --- man/stackctl.1.ronn | 3 ++- src/Stackctl/DirectoryOption.hs | 8 ++++++-- 2 files changed, 8 insertions(+), 3 deletions(-) diff --git a/man/stackctl.1.ronn b/man/stackctl.1.ronn index 5f9ec2f..8863fb2 100644 --- a/man/stackctl.1.ronn +++ b/man/stackctl.1.ronn @@ -8,7 +8,8 @@ stackctl(1) - manage CloudFormation Stacks through specifications ## OPTIONS * `-d`, `--directory`=: - Where to find specifications. Default is `.`. + Use the stack collection located at (default: current working + directory). * `--filter`=: Restrict specifications to those whose paths match any given . diff --git a/src/Stackctl/DirectoryOption.hs b/src/Stackctl/DirectoryOption.hs index a156a84..9acb7d9 100644 --- a/src/Stackctl/DirectoryOption.hs +++ b/src/Stackctl/DirectoryOption.hs @@ -30,7 +30,7 @@ instance HasDirectoryOption DirectoryOption where envDirectoryOption :: Env.Parser Env.Error DirectoryOption envDirectoryOption = Env.var (Env.str <=< Env.nonempty) "DIRECTORY" - $ Env.help "Operate on specifications in this directory" + $ Env.help directoryHelp directoryOption :: Parser DirectoryOption directoryOption = @@ -39,6 +39,10 @@ directoryOption = [ short 'd' , long "directory" , metavar "PATH" - , help "Operate on specifications in PATH" + , help directoryHelp , action "directory" ] + +directoryHelp :: String +directoryHelp = + "Use the stack collection located at PATH (default: current working directory)" From 7946d19c3c0e8712248f2f6ab1713ac11e00414d Mon Sep 17 00:00:00 2001 From: patrick brisbin Date: Fri, 17 Oct 2025 11:35:27 -0400 Subject: [PATCH 2/2] fix(docs): mention --filter in all subcommand help optparse-applicative offers a `header` or a `footer` info modifier, but they both put the text in the wrong place: either above or below everything. To get the text to appear after the one-line description, but before the options, we need to manually append it. Here is the updated help, ```console % 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 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. 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? ``` NOTE: `fullDescr` was removed because it is the default. `helpShowGlobals` was added because it was an oversight to not have it before. --- package.yaml | 1 + src/Stackctl/Subcommand.hs | 19 +++++++++++++++++-- stackctl.cabal | 3 ++- 3 files changed, 20 insertions(+), 3 deletions(-) diff --git a/package.yaml b/package.yaml index 7cd0871..865ec01 100644 --- a/package.yaml +++ b/package.yaml @@ -88,6 +88,7 @@ library: - monad-logger - mtl - optparse-applicative + - prettyprinter - resourcet - rio - semigroups diff --git a/src/Stackctl/Subcommand.hs b/src/Stackctl/Subcommand.hs index eb84864..ec7d33c 100644 --- a/src/Stackctl/Subcommand.hs +++ b/src/Stackctl/Subcommand.hs @@ -10,6 +10,8 @@ import Stackctl.Prelude import qualified Env import Options.Applicative +import Prettyprinter (pretty, vsep) +import Prettyprinter.Util (reflow) import Stackctl.AWS (handlingServiceError) import Stackctl.AutoSSO import Stackctl.CLI @@ -46,7 +48,9 @@ runSubcommand' title parseEnv parseCLI sp = do (options, act) <- applyEnv <$> Env.parse (Env.header $ unpack title) parseEnv - <*> execParser (withInfo title $ (,) <$> parseCLI <*> subparser sp) + <*> customExecParser + (prefs helpShowGlobals) + (withInfo title $ (,) <$> parseCLI <*> subparser sp) act options where @@ -78,4 +82,15 @@ runAppSubcommand f subOptions options = $ f subOptions withInfo :: Text -> Parser a -> ParserInfo a -withInfo d p = info (p <**> helper) $ progDesc (unpack d) <> fullDesc +withInfo d p = + info (p <**> helper) + $ progDescDoc + $ Just + $ vsep + [ pretty d + , "" + , reflow + $ "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." + ] diff --git a/stackctl.cabal b/stackctl.cabal index 7d0a84c..c920407 100644 --- a/stackctl.cabal +++ b/stackctl.cabal @@ -1,6 +1,6 @@ cabal-version: 1.18 --- This file has been generated from package.yaml by hpack version 0.37.0. +-- This file has been generated from package.yaml by hpack version 0.38.1. -- -- see: https://github.com/sol/hpack @@ -128,6 +128,7 @@ library , monad-logger , mtl , optparse-applicative + , prettyprinter , resourcet , rio , semigroups