git.taskfile.build/usage.md

layout

layout
layouts/base.njk

Usage

It is recommended to use simple shell alias to run the task file: 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                          |
|----------------------|--------|--------------------------------------|
| all                  |        | Run all tasks.                       |
| install              |        | Install build dependencies.          |
| lint                 |        | Lint code with prettier.             |
...

You can now run a task command with task install.

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

And if there is a command group run it with task all.

Completion

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

Completion for bash: /etc/bash_completion.d/task_completions

#!/usr/bin/env bash

_task_completions() {
    local cur prev commands
    cur="${COMP_WORDS[COMP_CWORD]}"
    prev="${COMP_WORDS[COMP_CWORD-1]}"

    commands=$(./task help | grep -A999 -e '---' | awk '{print $2}' | sed 's/^[[:space:]]*//' | grep -v '^$' | tr '\n' ' ')

    if [[ ${COMP_CWORD} == 1 ]]; then
        COMPREPLY=( $(compgen -W "${commands}" -- "${cur}") )
    elif [[ ${COMP_CWORD} == 2 ]]; then
        COMPREPLY=( $(compgen -f -- "${cur}") )
    else
        COMPREPLY=()
    fi
}

complete -F _task_completions task
complete -F _task_completions t

Completion for zsh: ~/.oh-my-zsh/completions/_task

#compdef task t

_arguments '1: :->tasks' '*: :_files'

case "$state" in
    tasks)
        args=$(./task help | grep -A999 -e '---' | awk '{print $2}' | sed 's/^[[:space:]]*//' | grep -v '^$' | tr '\n' ' ')
        args="$args help"
        _arguments "1:profiles:($args)"
        ;;
esac

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

Image

See taskfile.build/image for details.

Global default

Instead of setting up a task file for every ptoject, you can also set up only one with a fallback to the task file in the $PWD.

First create symlink from your shell bin folder to the task file 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 necessary.

Integration

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

GitHub Actions

Running task file 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 task file 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'
            }
        }
    }
}