Development workflow

The day-to-day cycle of working on Helix.

Setup

See overview/getting-started for prerequisites and the initial build. Key extra notes for development:

• Don't cargo install. Use cargo run -- <files> so iteration is fast.
• Set HELIX_RUNTIME=$PWD/runtime in your shell profile so the dev binary picks up the bundled queries and themes.
• Install mold for faster linking, and configure your global ~/.cargo/config.toml to use it.

Branch and code

git checkout -b fix-thing
# … hack …
cargo check
cargo run -- src/main.rs

Most commands hot-rebuild in <10s after the first build. The dev profile is unoptimised and fast. If you hit timing-sensitive bugs that don't repro in dev, switch to --release.

For UI work, the cargo run -- README.md workflow is canonical: open a small file, exercise the change, escape, repeat. To save your spot, use :earlier 1m to roll back time without committing.

Test as you go

cargo test --workspace                # unit + doc tests
cargo integration-test                # full app via TestBackend
cargo test -p helix-core              # one crate
cargo test -p helix-core movement     # one module's tests

The helix-core::test module (helix-core/src/test.rs) provides assert_apply_in_place_eq! and friends. They take literals like:

#[1|]hello[|2] world

where #[…] and …[…] mark range anchors and heads. Multi-cursor scenarios stay readable.

Lint

cargo fmt --all
cargo clippy --workspace --all-targets -- -D warnings

Both are required to pass CI. rustfmt.toml is empty — defaults are used.

Generated docs

After adding a static or typable command, or after touching language definitions, run:

cargo xtask docgen
git status                            # check book/src/generated/
git add book/src/generated/

The docs CI job will fail if you forget — and the failure message tells you what to do.

Commit and push

Helix doesn't enforce a particular commit style; the convention emerging from the log is short imperative summaries. Larger PRs split the change into logical commits. Don't squash unless you're rebasing on a stale base.

git push origin fix-thing
gh pr create   # or use the GitHub UI

CI

The CI matrix runs (see .github/workflows/build.yml):

• check (MSRV) — cargo check against the pinned Rust 1.90.
• test — cargo test --workspace + cargo integration-test on Linux, macOS, Windows, and ARM Linux.
• lints — cargo fmt --check, cargo clippy, cargo doc -D warnings.
• docs — cargo xtask query-check, cargo xtask theme-check, cargo xtask docgen + diff check.

A scheduled nightly run (the schedule trigger on the workflow) catches regressions in upstream tree-sitter grammars.

Code review

Reviewers focus on:

• Correctness — does the change preserve invariants (rope length math, selection ordering, transaction len/len_after)?
• Architecture — does it respect the crate boundaries? helix-core shouldn't gain helix-view knowledge, etc.
• UX consistency — keybindings follow the selection -> action convention, error messages route through editor.set_error instead of stderr.
• Tests — non-trivial logic gets a unit test or integration test.

Substantive changes often go through a "WIP" PR or a discussion issue first; the #helix-editor:matrix.org room is where most design questions get hashed out.

Releasing

Release management is a maintainer concern. The full checklist is in docs/releases.md. The TL;DR:

1. Open a release PR bumping workspace.package.version, regenerating Cargo.lock, and writing changelog notes.
2. After merge, tag and push: git tag -s -m "<tag>" -a <tag> then git push origin <tag>.
3. CI builds artifacts and creates a GitHub release.
4. Update the homebrew formula, post to r/rust, and link in this-week-in-rust.

Patch releases follow the same flow with the patch counter incremented.

When you're stuck

• Re-read docs/architecture.md — the high-level architecture often clarifies which layer a feature should live in.
• Look at how an adjacent feature did it — pattern matching is the fastest way to converge on idiomatic Helix code.
• Ask on Matrix. The community is friendly and the active maintainers are responsive.