Skip to content

feat: Add category option for task grouping in help output#354

Open
brolewis wants to merge 2 commits intonat-n:mainfrom
brolewis:feature/task-categories
Open

feat: Add category option for task grouping in help output#354
brolewis wants to merge 2 commits intonat-n:mainfrom
brolewis:feature/task-categories

Conversation

@brolewis
Copy link

@brolewis brolewis commented Feb 7, 2026

Description of changes

Adds support for an optional category option for tasks. If the category is included, it is used for grouping help output and the categories are ordered alphabetically. Added tests and docs as well.

A quick example I created from the user guide example:

  $ poe --help
  Poe the Poet (version 0.40.0)

  Usage:
    poe [global options] task [task arguments]

  Global options:
    -h [TASK], --help [TASK]
                          Show this help page and exit, optionally supply a task.
    --version             Print the version and exit
    -v, --verbose         Increase output (repeatable)
    -q, --quiet           Decrease output (repeatable)
    -d, --dry-run         Print the task contents but don't actually run it
    -C PATH, --directory PATH
                          Specify where to find the pyproject.toml
    -e EXECUTOR, --executor EXECUTOR
                          Override the default task executor
    -X KEY[=VALUE], --executor-opt KEY[=VALUE]
                          Set executor configuration for this run.
    --ansi                Force enable ANSI output
    --no-ansi             Force disable ANSI output

  Configured tasks:
    test                  Run the test suite

    dev
      serve                 Run the app in debug mode
      tunnel                Create an SSH tunnel to the production server
        --prod_host         Hostname of the production server [default: myapp.com]

Fixes #352

Pre-merge Checklist

  • New features (if any) are covered by new feature tests
  • New features (if any) are documented
  • Bug fixes (if any) are accompanied by a test (if not too complicated to do so)
  • poe check executed successfully
  • This PR targets the development branch for code changes or main if only documentation is updated

Adds support for an optional category option for tasks. If the category
is included, it is used for grouping help output and the categories are
ordered alphabetically. Added tests and docs as well.

A quick example I created from the user guide example:

```
  $ poe --help
  Poe the Poet (version 0.40.0)

  Usage:
    poe [global options] task [task arguments]

  Global options:
    -h [TASK], --help [TASK]
                          Show this help page and exit, optionally supply a task.
    --version             Print the version and exit
    -v, --verbose         Increase output (repeatable)
    -q, --quiet           Decrease output (repeatable)
    -d, --dry-run         Print the task contents but don't actually run it
    -C PATH, --directory PATH
                          Specify where to find the pyproject.toml
    -e EXECUTOR, --executor EXECUTOR
                          Override the default task executor
    -X KEY[=VALUE], --executor-opt KEY[=VALUE]
                          Set executor configuration for this run.
    --ansi                Force enable ANSI output
    --no-ansi             Force disable ANSI output

  Configured tasks:
    test                  Run the test suite

    dev
      serve                 Run the app in debug mode
      tunnel                Create an SSH tunnel to the production server
        --prod_host         Hostname of the production server [default: myapp.com]
```

Fixes nat-n#352
@brolewis brolewis mentioned this pull request Feb 7, 2026
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.

Support task groups

1 participant

Comments