Summary for overall taskfile

[boosh]

Tasks can be given descriptions and summaries. It'd be helpful if the overall taskfile could be given one as well to explain general usage. E.g. in my taskfile certain variables need passing in, while some are generated dynamically. Since these vars are used across multiple tasks it'd be good to just be able to provide general help instructions that'd be printed when running task --list.

[Zebradil]

It is an interesting idea. But until it is implemented, the following workaround might be sufficient.

I always use the following snippet in my Taskfiles:

tasks:
  default: ${GOTASK_BIN:-task} --list

It can be enhanced with an overview message:

tasks:
  default:
    cmds:
    - echo "This Taskfile is intended for this and that and has the following configurable parts: ..."
    - ${GOTASK_BIN:-task} --list

[andreynering]

I'll keep this issue open to track upvotes (👍s), i.e. how many people are interested in this.

[cristaloleg]

@Zebradil maybe --list-all ?

$ task --version
Task version: v3.15.0
$ task
task: [default] ${GOTASK_BIN:-task} --list
task: No tasks with description available. Try --list-all to list all tasks
$ 

[Zebradil]

@cristaloleg it depends. Usually, I provide desc for all "public" tasks, so they can be seen with --list. Sometimes I use --list-all but it also shows "internal" tasks, which are not meant to be used directly.

UPD. I might have misunderstood your point. The snippet I provided earlier indeed won't work on its own. It should be used together with other tasks in a Taskfile.yaml. In the form with --list the other tasks should have desc specified.

[pd93]

Sometimes I use --list-all but it also shows "internal" tasks, which are not meant to be used directly.

@Zebradil just for clarification, "internal" tasks are never displayed in the --list or --list-all output. The only difference between these is that --list-all will display tasks without a desc.

[Zebradil]

@pd93 yes, of course. It is just incorrect wording. By "internal" I meant not the go-task's internal tasks but tasks that are created by me and that are not supposed to be used directly.

For example, here useful:task uses util:require-args to ensure CLI_ARGS:

  useful:task:
    desc: Does something useful
    summary: |
      ...
    cmds:
      - task: util:require-args
        vars:
          TASK: '{{.TASK}}'
      - 'echo "2×2 = 4"'

  util:require-args:
    summary: Checks that CLI_ARGS are provided. Requires TASK var to be overridden.
    cmds:
      - '[[ -z "{{.CLI_ARGS}}" ]] && "${GOTASK_BIN:-task}" {{.TASK}} --summary && exit 1 || true'

When using directly, util:require-args is not really useful.