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

```bash

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

When developing new commands it's worth to have a look at the [patterns](/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:

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

See [library](/library) for more details on how to import and use the available commands.

### Global default

Instead of setting up a task file for every ptoject, you can also setup one file and add a fallback to a 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:

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

Then add this config to your shell profile:

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

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

For zsh:

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

For fish:

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

To see the completion script without applying it:

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

## Integration

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