From 734fb6b9ff84dbe94dc8990cb59038a05f26a918 Mon Sep 17 00:00:00 2001 From: Jackson Ferguson Date: Tue, 24 Feb 2026 18:35:10 -0800 Subject: [PATCH 1/3] feat(cli): implement custom HelpFormatter for clean CLI output - Introduce `PulsarHelpFormatter` subclassing `argparse.HelpFormatter` - Override `_format_action` to intercept `_SubParsersAction` and suppress the auto-generated `{command1,command2...}` metavar block - Update `ArgumentParser` in `main()` to utilize the custom formatter and suppress the default usage line --- src/git_pulsar/cli.py | 29 +++++++++++++++++++++++++++-- 1 file changed, 27 insertions(+), 2 deletions(-) diff --git a/src/git_pulsar/cli.py b/src/git_pulsar/cli.py index 0bbd1ed..d4047d4 100644 --- a/src/git_pulsar/cli.py +++ b/src/git_pulsar/cli.py @@ -952,9 +952,34 @@ def setup_repo(registry_path: Path = REGISTRY_FILE) -> None: ) +class PulsarHelpFormatter(argparse.HelpFormatter): + """Custom help formatter to streamline the CLI help output. + + This formatter intercepts the subparser action and strips the default + metavar block (the unwieldy comma-separated list of all commands) and + its associated trailing newline, leaving only the cleanly indented + subcommand list. + """ + + def _format_action(self, action: argparse.Action) -> str: + if isinstance(action, argparse._SubParsersAction): + # Skip the container action entirely to avoid the {cmd1,cmd2} block + # and its blank line, formatting only the nested subactions. + parts = [] + for subaction in self._iter_indented_subactions(action): + parts.append(self._format_action(subaction)) + return self._join_parts(parts) + + return super()._format_action(action) + + def main() -> None: """Main entry point for the Git Pulsar CLI.""" - parser = argparse.ArgumentParser(description="Git Pulsar CLI") + parser = argparse.ArgumentParser( + description="Git Pulsar CLI", + usage=argparse.SUPPRESS, + formatter_class=PulsarHelpFormatter, + ) # Global flags parser.add_argument( @@ -965,7 +990,7 @@ def main() -> None: ) subparsers = parser.add_subparsers( - dest="command", help="Service management commands" + dest="command", ) # Subcommands From e991215ce796107237e5f7b55b5292e0644095bb Mon Sep 17 00:00:00 2001 From: Jackson Ferguson Date: Tue, 24 Feb 2026 18:36:17 -0800 Subject: [PATCH 2/3] feat(cli): group subcommands logically in help output - Update `PulsarHelpFormatter` to categorize subcommands based on their domain (Backup Management, Repository Control, Maintenance, Service). - Inject custom headers and spacing during the subaction iteration phase to visually separate command clusters. --- src/git_pulsar/cli.py | 46 +++++++++++++++++++++++++++++++++++-------- 1 file changed, 38 insertions(+), 8 deletions(-) diff --git a/src/git_pulsar/cli.py b/src/git_pulsar/cli.py index d4047d4..6f2fd4d 100644 --- a/src/git_pulsar/cli.py +++ b/src/git_pulsar/cli.py @@ -955,19 +955,49 @@ def setup_repo(registry_path: Path = REGISTRY_FILE) -> None: class PulsarHelpFormatter(argparse.HelpFormatter): """Custom help formatter to streamline the CLI help output. - This formatter intercepts the subparser action and strips the default - metavar block (the unwieldy comma-separated list of all commands) and - its associated trailing newline, leaving only the cleanly indented - subcommand list. + This formatter intercepts the subparser action, strips the default + metavar block, and groups the subcommands into logical categories + with custom headers. """ def _format_action(self, action: argparse.Action) -> str: if isinstance(action, argparse._SubParsersAction): - # Skip the container action entirely to avoid the {cmd1,cmd2} block - # and its blank line, formatting only the nested subactions. parts = [] - for subaction in self._iter_indented_subactions(action): - parts.append(self._format_action(subaction)) + + # Define logical command clusters based on the project structure + groups = { + "Backup Management": ["now", "sync", "restore", "diff", "finalize"], + "Repository Control": [ + "status", + "config", + "list", + "pause", + "resume", + "remove", + "ignore", + ], + "Maintenance": ["doctor", "prune", "log"], + "Service": ["install-service", "uninstall-service"], + "General": ["help"], + } + + subactions = list(self._iter_indented_subactions(action)) + + for group_name, commands in groups.items(): + # Filter the standard argparse subactions into our defined groups + group_actions = [a for a in subactions if a.dest in commands] + if not group_actions: + continue + + # Inject the group header with standard argparse indentation + parts.append(f"\n {group_name}:\n") + + # Render the commands belonging to this group + self._indent() + for subaction in group_actions: + parts.append(self._format_action(subaction)) + self._dedent() + return self._join_parts(parts) return super()._format_action(action) From 0f966952a6ce538a9ea28ea450e579162735df67 Mon Sep 17 00:00:00 2001 From: Jackson Ferguson Date: Tue, 24 Feb 2026 18:39:58 -0800 Subject: [PATCH 3/3] refactor(cli): hide default help flag from options block - Initialize `ArgumentParser` with `add_help=False` to strip the default help behavior. - Manually re-implement `-h` and `--help` flags using `action="help"` but map their help strings to `argparse.SUPPRESS` so they remain functional without cluttering the final options block. --- src/git_pulsar/cli.py | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/src/git_pulsar/cli.py b/src/git_pulsar/cli.py index 6f2fd4d..4f2c4ad 100644 --- a/src/git_pulsar/cli.py +++ b/src/git_pulsar/cli.py @@ -1006,9 +1006,18 @@ def _format_action(self, action: argparse.Action) -> str: def main() -> None: """Main entry point for the Git Pulsar CLI.""" parser = argparse.ArgumentParser( - description="Git Pulsar CLI", usage=argparse.SUPPRESS, formatter_class=PulsarHelpFormatter, + add_help=False, # Disable the default help injection + ) + + # Manually re-add the help flags but suppress them from the visual output + parser.add_argument( + "-h", + "--help", + action="help", + default=argparse.SUPPRESS, + help=argparse.SUPPRESS, ) # Global flags