Usage¶

Open a terminal in folder with a task file. Type task help and you should get an output like this:

task <command> [options]

commands:

| Command | Option | Description                     |
|---------|--------|---------------------------------|
| help    | [grep] | Show help for commands.         |
| install |        | Install build dependencies.     |
| lint    |        | Run pre-commit.                 |
| version |        | Show version of required tools. |

This command shows the help table.

Choose a task and run it with task <command> [option].

With the command switch case it is also possible to run multiple commands: task install,lint

Install¶

The taskfile.build site also provides library with reusable commands.

You can clone and install the project as followed:

git clone https://git.taskfile.build "$HOME/taskfile.build"
"$HOME/taskfile.build/install"

The install script sets up the global default Taskfile and adds the t alias.

Global default¶

The install script symlinks $HOME/taskfile.build/task.template to $HOME/.local/bin/task and adds a task() shell function to your profile.

When you run task in a directory that contains a local ./task file, that file is executed. Otherwise, the global default $HOME/.local/bin/task is used. This makes the Taskfile library commands available in any directory.

The t alias is a shorthand for task:

alias t='task'

Completion¶

With the output of task help commands can be auto-completed.

To get shell completion setup the global default and proceed with these instructions:

For bash:

task setup-completion bash >> ~/.bashrc
source ~/.bashrc

For zsh:

task setup-completion zsh >> ~/.zshrc
source ~/.zshrc

For fish:

task setup-completion fish >> ~/.config/fish/config.fish
source ~/.config/fish/config.fish

To see the completion script without applying it:

task setup-completion bash  # Shows bash completion script
task setup-completion zsh   # Shows zsh completion script
task setup-completion fish  # Shows fish completion script

The completion also works for the task alias alias t='task'.

Configure¶

You can extend any Taskfile by add help row and a named bash function.

When developing new commands it's worth to have a look at the patterns page. It gives you an idea of what bash structures can be used and applied.

Image¶

Any project with a Taskfile can be set up with the Taskfile Docker image.

See taskfile.build/image for details.

Integration¶

Whenever an application uses a domain specific language (DSL) ensure that the DSL-implementation calls a Taskfile command.

GitHub Actions¶

Running Taskfile commands in GitHub Actions is highly recommended. This way you can run the same CI/CD procedures in the GitHub runner as you would on your localhost.

Here is an example for .github/workflows/build.yml:

on:
    pull_request:
        branches:
            - 'main'
    push:
        branches:
            - 'main'

jobs:
    build:
        name: Build
        runs-on: ubuntu-latest
        steps:
            - name: Checkout
              uses: actions/checkout@v4
            - name: Clone taskfile
              run: ./task clone-taskfile
            - name: Install uv
              uses: astral-sh/setup-uv@v6
            - name: Install
              run: ./task install
            - name: Lint
              run: ./task lint

Jenkins¶

Run Taskfile commands in a Jenkinsfile:

pipeline {

    agent any

    stages {
        stage('version') {
            steps {
                script {
                    currentBuild.description = sh (script: 'git log -1 --pretty=%B', returnStdout: true).trim()
                }
                sh './task version'
            }
        }
        stage('install') {
            steps {
                sh './task install'
            }
        }
        stage('lint') {
            steps {
                sh './task lint'
            }
        }
    }
}