setup-trunk

Setup Trunk

Overview

Trunk.io is a meta-linter and git hook manager. Its core principle is "hold-the-line": existing violations are acknowledged and ignored initially, but new violations on changed files are blocked. This lets teams adopt linting incrementally without a big-bang cleanup. This skill covers first-time integration and configuration. Running trunk day to day is a different job — trunk check / trunk fmt at milestones, cache corruption, aligning trunk-pinned linter versions with the workspace, vulnerability triage — and is out of scope here.

Initialization Flow

1. Inspect the repository before selecting linters

Do not start from a memorized linter bundle. First inspect the repository's manifests and lockfiles, existing CI workflows, declared package scripts, language and generated-file layout, and any existing linter configuration. Use that evidence to identify tools the project already runs, file types that actually exist, and checks CI already owns.

git ls-files | grep -E '(^|/)(package.json|pubspec.yaml|pyproject.toml|Cargo.toml|go.mod|Podfile)$'
git ls-files '.github/**'
git ls-files | grep -Ei '(^|/)([^/]*(eslint|prettier|ruff|markdownlint|shellcheck)[^/]*)$'

Read the files found, including scripts in manifests and the commands used by CI, before proposing lint.enabled. Enable a linter only when a repository artifact or an explicit user requirement supports it; do not infer that mobile, web, infrastructure, and documentation checks all belong in the same repository.

2. Run trunk init

trunk init

The wizard prompts for:

1. Account connection (optional for local-only use)
2. Linter auto-detection based on files in the repo
3. Git hooks setup (built-in actions)
4. Initial full-repo scan to snapshot existing violations

For open-source repos where you contribute a PR to someone else's codebase and don't want to commit trunk config:

trunk init  # then: trunk config hide

trunk config hide adds .trunk/ to .gitignore, keeping the config local. Alternatively, trunk init --single-player-mode does both in one step (verified in trunk init --help: "initialize trunk with a gitignored config, run 'trunk config share' to undo").