Task Reference

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

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 management/, not in YAML. This keeps the Taskfile readable and the logic testable.

Platform detection is automatic. Tasks that need platform awareness detect it at runtime using system checks.

Shell Build

task shell:build         # Build shell files from machine manifest
MACHINE=ubuntu-lxc-server task shell:build  # Build for specific machine

Windows Setup

task windows:setup       # One-time Windows Git Bash setup (run from WSL)

Installation

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

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

Machine manifests in management/machines/ 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 management/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:

brew install go-task  # macOS

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