---
layout: layouts/base.njk
---

# Usage

Running the task file requires a shell alias: `alias task='./task'`

Show the available commands with `task help`.

From the specification the project can be installed with `task install`.

Execute all commands 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`

```bash
#!/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`

```bash
#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](/image) for details.

## Integration

The task file is intended to be integrated into the shell setup. Whenever an applicatio uses a domain specific language (DSL) ensure that the DSL calls the task file. Most you'll see DSLs to describe build pipelines.

### 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 `

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

```groovy
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'
            }
        }
    }
}%
```