Skip to content

feat(cli): overhaul help formatting with custom argparse HelpFormatter#55

Merged
JacksonFergusonDev merged 3 commits intomainfrom
feat/help-format
Feb 25, 2026
Merged

feat(cli): overhaul help formatting with custom argparse HelpFormatter#55
JacksonFergusonDev merged 3 commits intomainfrom
feat/help-format

Conversation

@JacksonFergusonDev
Copy link
Owner

@JacksonFergusonDev JacksonFergusonDev commented Feb 25, 2026

Description

The default argparse output for git pulsar help was generating excessive noise, conflating all 18 subcommands into a single massive usage block and an unreadable {command1,command2...} meta-variable string. This PR brings the CLI's help aesthetic in line with the project's "Signal vs. Noise" philosophy by explicitly overriding argparse internals.

Changes

  • Custom Formatter (PulsarHelpFormatter): Subclassed argparse.HelpFormatter to intercept _SubParsersAction during rendering, allowing us to completely bypass the default container formatting and its trailing whitespace artifacts.
  • Logical Grouping: Clustered subcommands into distinct categories (Backup Management, Repository Control, Maintenance, Service) that map directly to the documentation structure in the README.md.
  • Usage Suppression: Suppressed the auto-generated usage: line to keep the top-level description clean.
  • Options Decluttering: Stripped the redundant -h, --help flags from the final options block by initializing the parser with add_help=False and manually re-injecting them as argparse.SUPPRESS.

Visual Impact

Before:

usage: git-pulsar [-h] [--env]
                  {install-service,uninstall-service,now,restore,finalize,pause,resume,status,diff,list,log,help,remove,sync,doctor,config,ignore,prune} ...

Git Pulsar CLI

positional arguments:
  {install-service,uninstall-service,now,restore,finalize,pause,resume,status,diff,list,log,help,remove,sync,doctor,config,ignore,prune}
                        Service management commands
    install-service     Install the background daemon
    uninstall-service   Uninstall the background daemon
    now                 Run backup immediately (one-off)
    restore             Restore a file from the backup branch
    finalize            Squash backup stream into main and reset history
    pause               Suspend backups for current repo
    resume              Resume backups for current repo
    status              Show daemon and repo status
    diff                Show changes between working dir and backup
    list                List registered repositories
    log                 Tail the daemon log file
    help                Show this help message
    remove              Stop tracking current repo
    sync                Sync with latest session
    doctor              Clean registry and check health
    config              Open global config file
    ignore              Add pattern to .gitignore
    prune               Clean up old backup refs

options:
  -h, --help            show this help message and exit
  --env, -e             Bootstrap macOS Python environment (uv, direnv, VS Code)

After:

positional arguments:

  Backup Management:
    now                 Run backup immediately (one-off)
    sync                Sync with latest session
    restore             Restore a file from the backup branch
    diff                Show changes between working dir and backup
    finalize            Squash backup stream into main and reset history

  Repository Control:
    status              Show daemon and repo status
    config              Open global config file
    list                List registered repositories
    pause               Suspend backups for current repo
    resume              Resume backups for current repo
    remove              Stop tracking current repo
    ignore              Add pattern to .gitignore

  Maintenance:
    doctor              Clean registry and check health
    prune               Clean up old backup refs
    log                 Tail the daemon log file

  Service:
    install-service     Install the background daemon
    uninstall-service   Uninstall the background daemon

  General:
    help                Show this help message

options:
  --env, -e             Bootstrap macOS Python environment (uv, direnv, VS Code)

- 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
- 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.
- 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.
@JacksonFergusonDev JacksonFergusonDev changed the title Feat/help format feat(cli): overhaul help formatting with custom argparse HelpFormatter Feb 25, 2026
@JacksonFergusonDev JacksonFergusonDev merged commit 8375c64 into main Feb 25, 2026
4 checks passed
@JacksonFergusonDev JacksonFergusonDev deleted the feat/help-format branch February 25, 2026 02:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant