---
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 ouput like this:

```bash

task <command> [options]

commands:

| Command              | Option     | Description                                |
|----------------------|------------|--------------------------------------------|
| all                  |            | Run all tasks.                             |
...
```

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`

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

## Default

Instead of setting up a task file for every ptoject, you can also set up one and fallback to the local task file.

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

Create the symlink:

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

For your shell set this config:

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

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

Remove the at the beginning of this document recommended alias.

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

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