Quickstart

Quickstart

Go from an empty git repository to your first rtunk check report in a few minutes: initialize, enable one linter, run the check, then fix or ignore what it finds. This page assumes rtunk is installed and that you have git and network access (rtunk downloads the linter on first use).

rtunk init   # pick yamllint in the picker; non-interactively: rtunk linters enable yamllint
rtunk check

Initialize rtunk in a repository

Run init at the root of a git repository. This guide uses a repository holding one badly formatted YAML file.

$ printf 'name:   test\nlist: [a,  b]\n' > example.yaml
$ rtunk init
initialized rtunk at /path/to/repo/.rtunk/rtunk.yaml
next: rtunk linters enable, rtunk actions enable, rtunk download
linked /path/to/repo/.rtunk
then: rtunk git-hooks sync to install the git hooks of the enabled actions

On a terminal, init also opens the linters and actions pickers and downloads what you enabled (the next: line is for non-interactive use).

Without a .trunk/, init creates .rtunk/rtunk.yaml with no linter enabled. It pins the trunk plugins repository as the source of linter definitions.

Warning

Coming from trunk? If .trunk/trunk.yaml exists, init migrates it (and configs/, user_trunk.yaml, user.yaml) to .rtunk/ and removes .trunk/. To keep trunk's layout, skip init and run rtunk check directly; see Migrating from trunk.

Enable a linter

rtunk linters enable yamllint

The command prints nothing on success and adds yamllint to lint.enabled in .rtunk/rtunk.yaml:

lint:
  enabled:
    - yamllint

Run the check

With no paths, rtunk check checks the files that changed. In a repository without commits, that is every file. rtunk downloads and installs yamllint on the first run, so that run takes longer.

$ rtunk check
▲ yamllint         done     4 issues
.rtunk/rtunk.yaml  (1)
  1:1  medium  missing document start "---"  yamllint/document-start

example.yaml  (3)
  1:1   medium  missing document start "---"  yamllint/document-start
  1:8   high    too many spaces after colon   yamllint/colons
  2:11  high    too many spaces after comma   yamllint/commas

Checked 2 files with 1 linter in 0.2s
✖ 4 issues (2 high · 2 medium · 0 low)
rtunk: rtunk: check found 4 issue(s)

Each finding reads line:column severity message linter/rule. The command exits 1 when it finds issues and 0 when the tree is clean, so it works as a CI gate. check is read-only: it never modifies files.

Fix or ignore what it found

Fix the file, then check it again. Pass a path to check one file regardless of git state:

$ printf -- '---\nname: test\nlist: [a, b]\n' > example.yaml
$ rtunk check example.yaml
✔ yamllint         done     clean
Checked 1 file with 1 linter in 0.1s
✔ no issues

To accept a finding instead, add an rtunk-ignore comment on the offending line, naming the rule:

$ cat example.yaml
---
name: test
list: [a,  b]  # rtunk-ignore(yamllint/commas): demo
$ rtunk check example.yaml
✔ yamllint         done     clean
Checked 1 file with 1 linter in 0.1s
✔ no issues · 1 suppressed

Note

yamllint requires two spaces before an inline comment, as above. trunk-ignore(...) comments work the same way. Every form is in the ignore syntax reference.

Where to go next

• Checking code — file selection, --fix, output formats and exit codes
• Managing linters — list, enable and disable linters
• Formatting code — formatters run through rtunk fmt, not check
• Actions and git hooks — run check automatically before a commit