Skip to content

Conversation

laurensmiers
Copy link

@laurensmiers laurensmiers commented Sep 16, 2025

Previously,
If a task did NOT have positional arg, passing '--help' to a task iso passing it to invoke directly worked as expected: --help would print the per-task help:

> invoke my_task --help # prints help of my_task which has no positional arguments

However, when passing '--help' to a task with (mandatory) positional arg, the string would just be passed to the task and executed.
This is not the expected behaviour of '--help', we would expect the per-task help to be printed.

With these commits,
we attempt to fix this issue by detecting when '--help/-h' is passed to a task and stop the parsing to print the per-task help.
Additionally, when a task is called without mandatory arg, the per-task help is now also printed.

As highlighted in #205, this will break any user-task having the --help OR -h cli options:

  • --help
    As stated in previous discussions, users would rather expect --help to produce a help text
    than their task be called.
  • -h
    This one is sadly a regression which will impact existing user scripts.
    However, IMO, this feels like a small price to pay for more unix-like tool behaviour of invoke.

As an example of what this PR behaves like, f.e. with this tasks.py:

from invoke import task

@task()
def no_arg(c):
    print(f"Invoked dummy!")

@task()
def one_arg(c, name):
    print(f"Invoked with param '{name}'!")

@task()
def two_arg(c, name, o_name):
    print(f"Invoked with param '{name}' and '{o_name}!")

Previous behaviour

  • With '--help':
> inv no-arg --help  # prints help
> inv one-arg --help # prints "Invoked with param '--help'"
> inv two-arg --help # prints "'two-arg' did not receive required positional arguments: 'name', 'o_name'"
  • Without '--help':
> inv no-arg   # prints 'Invoked dummy!'
> inv one-arg  # prints "'one-arg' did not receive required positional arguments: 'name'"
> inv two-arg  # prints "'two-arg' did not receive required positional arguments: 'name', 'o_name'"

New behaviour

  • With '--help':
> inv no-arg --help  # prints help
> inv one-arg --help # prints help
> inv two-arg --help # prints help
  • Without '--help':
> inv no-arg   # prints 'Invoked dummy!'
> inv one-arg  # prints "'one-arg' did not receive required positional arguments: 'name'" + help
> inv two-arg  # prints "'two-arg' did not receive required positional arguments: 'name', 'o_name'" + help

Feel free to propose different solutions, disagree with, comment on, discard, edit, use any of the proposed changes in this PR.

This fixes the invocation of a my_task which has mandatory/positional arguments:
```bash
> inv my_task --help
```

When detecting a missing positional arg, we check if the token is '--help/-h'.
If so, we store the task/context name to print help for it later and flag it the task/context to be completed without checks.

Signed-off-by: laurensmiers <[email protected]>
This will f.e. print the help of a task when it is not given its mandatory args:
```bash
> # Prints help if my_task expects mandatory positional arg
> inv my_task
```

If no name is available for the context, f.e. the core/None context,
we skip the specific task print since this means it was not a 'user' task which failed.

Signed-off-by: laurensmiers <[email protected]>
Signed-off-by: laurensmiers <[email protected]>
Signed-off-by: laurensmiers <[email protected]>
Signed-off-by: laurensmiers <[email protected]>
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