List experiment

[pd93]

Context

This is a proposal for a new API for the --list flag. It aims to unify the API for outputting tasks in a more consistent and intuitive way.

Obviously, we cannot break the API for the existing --list flag in v3, so I am proposing that the new API go behind an experiment (i.e. TASK_X_LIST). This will allow us to iterate and gather feedback on the design without worrying about breaking anything for existing users. The flag should come with a warning to users that it does not have a backward-compatible guarantee and should not be relied upon for scripts/CI. If the experiment is successful, then we could replace the existing --list and --list-all flags in a new major version release.

We may also want to consider the naming of the flag itself. In this proposal I have continued to call the flag --list, but in theory this flag could be used to format/display all sorts of things (tasks, taskfiles, DAGs, Profiling Reports etc). Maybe a more generic name would be suitable. Some ideas below:

• --list
• --query
• ???

This would also allow us to release the functionality in v3 since the change would not be breaking.

Design

This proposal has 3 main aims:

• Consolidate the output of tasks into a single --list flag.
  • Any other flags related to the output should be implemented as "subflags" that supplement the --list flag.
• Make the design more intuitive and consistent with other well-known CLIs.
• Tidy up the code responsible for output and decouple it from the executor. This make it easier to:
  • Add new filters and formats
  • Write functional unit tests.

The following subsections describe the proposed API design in more detail:

Tags

tags is a new field that can be added to a task. It allows the user to attach some arbitrary metadata to a task that can then be used later for filtering and grouping. Multiple tags can be specified per task:

version: 3

tasks:
  foo:
    desc: 'Task foo'
    tags: [foo, bar]
  bar:
    desc: 'Task bar'
    tags: [foo]

Filtering (--filter)

Filtering allows the user to filter the list of tasks using task attributes. We can do this by supporting some basic wildcard functionality (or maybe regex?). The flag can be supplied multiple times to add more filters. These filters are applied in the order specified. ! can be prefixed to a filter to negate its effect (i.e. it becomes an exclusion). Initial supported filtering attributes are:

• name
• desc
• tags

Example usage:

• task --list --filter name=foo* - Only lists tasks that start with "foo".
  • "foo1" and "foo2" will be included.
• task --list --filter name={foo,bar}* - Only lists tasks whose names start with "foo" or "bar".
  • "foo1" and "foo2" will be included.
  • "bar1" and "bar2" will be included.
• task --list --filter !desc= - Removes tasks with no description (matches the current --list behavior).
  • We could also allow for the shorthand --filter !desc for this.
• task --list --filter tags=foo - Only lists tasks with the tag "foo".

Sorting (--sort/--sort-by)

Not much change here. This will work the same way as it does now.

Example usage:

• task --list --sort none
• task --list --sort alphanumeric

However, we could add some additional sorting options:

• task --list --sort alphanumeric --reverse - Reverse the sort order
• task --list --sort-by desc - Sort by desc instead of name

Formatting (--format)

Instead of having a separate flag for each format (we only have --json right now), we can use a single --format flag that accepts a string. This will allow us to add new formats in the future without having to add new flags.

Example usage:

• task --list --format text - default
• task --list --format json

In addition to this, we could create an API for raw string formatting using templating:

• task --list --format '{{.Name}} - [{{.Aliases}}]'

Quiet (--quiet)

The current --silent flag is a bit of a misnomer. It doesn't silence the output, it just prints a non-formatted list. I propose that we follow the more conventional --quiet flag for this style of unformatted list. See the Docker CLI as a reference.

Example usage:

• task --list --quiet
• task --list -q

There is no reason this does not also apply to other uses of silent too (e.g. in the Taskfile or when calling tasks using --silent).

.taskrc.yml

In addition to the above flags. Users might find it useful to change the defaults for their project. We could use our new configuration file to achieve this rather than complicating the Taskfile schema:

# .taskrc.yml
format: json
sort: none
sort-by: name
filters:
  - name=foo*
  - tags=bar

Specifying a flag on the command line should override the .taskrc.yml settings.

[task-bot]

This issue has been marked as an experiment proposal! 🧪 It will now enter a period of consultation during which we encourage the community to provide feedback on the proposed design. Please see the experiment workflow documentation for more information on how we release experiments.

[iainvm]

Could this use a --query flag, so it doesn't conflict allowing people to keep --list but test this experiment?

[pd93]

Could this use a --query flag, so it doesn't conflict allowing people to keep --list but test this experiment?

True! There is no reason why this has to be a breaking change. We could continue to support --list in v3 and deprecate its usage if we used another name. Something like --query is a more generic name if we wanted to output other types of data too. I've updated the proposal with this suggestion.