Usage¶

It is recommended to use simple shell alias to run the Taskfile: alias task='./task'

Start with showing the available commands: task help

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. |

You can now run a task command with task install.

It is also possible to run multiple commands without parameters: task install,lint

Commands¶

The specification provides the skeleton to implement new commands. Simply add a bash function and help table entry to extend the Taskfile.

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

Library¶

The repository of this website also provides a library of reusable commands.

Clone the repository into your home folder:

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

See library for more details on how to import and use the available commands.

Global default¶

Instead of setting up a Taskfile for every ptoject, you can also setup one file and add a fallback to a Taskfile in the $PWD.

First create symlink from your shell bin folder to the Taskfile template. It is recommended to use the $HOME/.local/bin/ folder.

Create the symlink:

ln -sf "$HOME/taskfile.build/task.template" "$HOME/.local/bin/task"

Then add this config to your shell profile:

export PATH="$HOME/.local/bin:$PATH"

task() {
    if [[ -f "./task" && -x "./task" ]]; then
        ./task "$@"
    else
        "$HOME/.local/bin/task" "$@"
    fi
}

Remove the alias task='./task' alias from your profile. It is no longer required.

Completion¶

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

To set up 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'.

Image¶

See taskfile.build/image for details.

Integration¶

The Taskfile is intended to be integrated into every shell interaction. Whenever an application uses a domain specific language (DSL) ensure that the DSL-implementation calls a Taskfile command. Most often you will see DSLs in build pipelines such as the following.

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 do on your localhost.

The GitHub Actions config is simple: .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 Jenkins: 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'
            }
        }
    }
}