Skip to content

Task Reference

This dotfiles repository uses go-task/task for automation from inside the repo. The Taskfile is intentionally minimal - complex installation logic lives in dedicated shell scripts.

Every task here has a dotfiles CLI equivalent that works from any directory, and both call the same scripts under install/ops/. See Management Interface for the layering.

Available Tasks

Run task --list to see all available tasks:

task --list

task symlinks:link      # Create symlinks from dotfiles to home directory
task symlinks:relink    # Remove and recreate all symlinks
task symlinks:check     # Verify symlinks are correct
task symlinks:show      # Show all configured symlinks
task symlinks:unlink    # Remove all symlinks

Symlinks use a two-layer system: common configs first, then platform-specific overlay.

Testing

task test               # Run all BATS tests
task test:unit          # Run unit tests
task test:integration   # Run integration tests
task test:watch         # Run tests on file changes (requires entr)

Documentation

task docs:serve         # Serve documentation site locally (localhost:8000)
task docs:build         # Build static documentation site
task docs:deploy        # Deploy documentation to GitHub Pages

Philosophy

Tasks are for orchestration, not wrappers. The Taskfile coordinates multi-step workflows while keeping simple operations accessible via their native commands.

Minimal by design. Complex installation logic lives in shell scripts under install/, not in YAML. This keeps the Taskfile readable and the logic testable.

Platform detection is automatic. It lives in install/platform-detection.sh and is used by the install/ops/ scripts, not reimplemented in YAML.

Windows Setup (WSL only)

task windows:setup                # One-time Git Bash setup via winget (run from WSL)
task windows:sync                 # Sync shell files to Windows Git Bash (run from WSL)
task windows:bundle               # Bundle Windows tool binaries into a .tar.gz (any machine)
task windows:offline -- <archive> # Install tools from a bundle when winget is blocked (WSL)

windows:bundle downloads the Windows .exe for each shell tool from GitHub releases into a single archive that can be moved to a network-restricted machine, where windows:offline installs them without touching the network. Use this pair when winget is blocked; otherwise windows:setup handles everything online.

Installation

Full installation is handled by install.sh with a machine manifest, not Tasks:

cd ~/dotfiles
bash install.sh --machine archlinux-personal-workstation

Machine manifests in install/manifests/ define what gets installed per computer type. The install script reads the manifest to determine platform, tools, and configuration.

Direct Commands

For operations not covered by Tasks, use native commands:

# Package updates
brew update && brew upgrade       # macOS
sudo apt update && sudo apt upgrade  # WSL
sudo pacman -Syu                  # Arch

# Python tools
uv tool upgrade --all
uv tool list

# Node.js
npm update -g
npm list -g --depth=0

# Theme management
theme apply <name>
theme list
theme current

Package Definitions

All package versions and configurations are centralized in install/packages.yml:

  • Runtime versions (Go, Node, Python)
  • GitHub binaries (neovim, lazygit, yazi, fzf)
  • Cargo packages
  • npm global packages
  • uv tools
  • Shell and tmux plugins

Troubleshooting

Task Not Found

Install task:

go install github.com/go-task/task/v3/cmd/task@latest

Permission Errors

Some operations require sudo (apt/pacman). You'll be prompted when needed.

List All Tasks

task --list-all      # Shows all tasks including internal ones

See Also