simit
simit is a semver-aware commit helper for Rust projects.
The command bumps the selected package version in Cargo.toml, updates
Cargo.lock when present, stages only the version files it changed, delegates
to git commit, and creates a signed release tag named exactly like the new
version with the message Release <version>.
Use --no-tag to skip tag creation:
Use --no-sign to create an unsigned lightweight tag in environments where
GPG signing is unavailable:
Preview a release commit without touching the worktree:
For workspaces with more than one package, choose the target package:
Run the full local release flow, including checks and a strict Keep a Changelog update:
simit release runs cargo test, cargo clippy --all-targets --all-features -- --deny warnings, promotes CHANGELOG.md from [Unreleased] when that file
exists, commits, and tags locally. It does not push. Use --no-changelog to
skip changelog promotion for one release.
If a pushed release tag runs CI on a bad commit, commit the fix and move the
current-version tag to HEAD:
Without --push, sync-up only moves the local tag.
Project registry
Simit records projects it has acted on in a per-user registry. Inspect that
state with simit projects:
The JSON output is intended for scripts and AI agents that need to find all
projects where simit manages a feature such as flake, CI, or packaging.
Run simit projects discover <ROOT> once per machine to add existing
simit-managed projects to the registry.
Changelog management
Initialize a canonical Keep a Changelog file:
Add entries under [Unreleased] with one of the standard section kinds:
Promote [Unreleased] into a dated release section:
Validate or inspect a changelog section:
simit release automatically runs the same promotion logic when CHANGELOG.md
is present, so the normal local release flow is:
CI wiring
Generate lightweight Rust CI and crates.io publish workflows for a repository:
Forgejo workflows use direct Rust container jobs by default, even when the
repository has a flake.nix. The default container is derived from
package.rust-version: rust:<version>-bookworm for current MSRVs, or
rust:<version>-trixie once the matching official tag exists. Without
rust-version, simit uses rust:bookworm. MSRV is only checked when
--with-msrv is requested.
Forgejo runner labels are user infrastructure. Before generating Forgejo workflows, configure your local runner fleet in the simit user config:
The config lives at $XDG_CONFIG_HOME/simit/config.toml, or
~/.config/simit/config.toml when XDG_CONFIG_HOME is unset. init ci
selects Forgejo runners from [ci.defaults.forgejo]; if no matching default is
configured, it fails instead of guessing a non-portable label. Use --runner
only for a one-off explicit label override:
Use --runtime nix only for workflows that intentionally need flake outputs,
such as cross-platform binary builds or release artifacts. Forgejo Nix
workflows use the configured nix runner default and do not run on
pull-request events:
Omnix CI (--with-om-ci)
Use --with-om-ci with --runtime nix to replace the generated Nix flake
check and cargo dev-shell test steps with Omnix om ci:
Replace mode is the default when --with-om-ci is set. It trusts the flake's
checks.* to cover the project's test, clippy, fmt, and doc gates. Projects
using simit's generated crane flake satisfy that contract. Custom flakes
([flake].mode = "custom") must audit [flake.expected_outputs].checks
before enabling replace mode; otherwise CI can go green while skipping work the
legacy nix develop -c cargo ... steps used to run.
For Forgejo, replace mode emits this CI workflow:
name: CI
on:
push:
branches:
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
jobs:
test:
runs-on: atlas
steps:
- name: Checkout
uses: https://code.forgejo.org/actions/checkout@v4
- name: Run om ci
env:
OMNIX_REF: "github:juspay/omnix/v1.3.2"
run: nix run "$OMNIX_REF" -- ci run
Use --om-ci-augment when the flake checks are not yet complete. Augment mode
runs om ci first, then keeps the legacy Nix-runtime cargo steps:
name: CI
on:
push:
branches:
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
jobs:
test:
runs-on: atlas
steps:
- name: Checkout
uses: https://code.forgejo.org/actions/checkout@v4
- name: Run om ci
env:
OMNIX_REF: "github:juspay/omnix/v1.3.2"
run: nix run "$OMNIX_REF" -- ci run
- name: Check flake
run: nix flake check
- name: Test
run: nix develop -c cargo test
- name: Clippy
run: nix develop -c cargo clippy --all-targets -- --deny warnings
- name: Package crate
run: nix develop -c cargo package --allow-dirty
Pin the Omnix flakeref with --omnix-ref, project config, or user config. The
resolution order is CLI --omnix-ref > project [ci].omnix_ref > user
[ci.tools.omnix].ref > simit's pinned default.
Use --check in CI to make sure committed workflows still match simit's
generated output:
When [ci].extra_setup, [ci].extra_env, or [ci].required_secrets are set
in project config, simit renders them into every generated CI, publish, and
artifact workflow. Extra setup runs after checkout/toolchain setup and before
tests or builds; extra env is job-level environment; required secrets are
documented as workflow comments but are not read locally.
init ci always renders a separate publish-crate.yaml workflow. That
workflow runs only on exact semver tag pushes such as 0.9.0, verifies that
the tag matches the Cargo package version, verifies the signed tag against
keys/maintainers.gpg, runs a publish dry run, and publishes with the
CRATES_IO_API_TOKEN secret. On generation, init ci discovers the release
signing key from [release.signing].key, git config user.signingkey, or
--maintainer-key, then writes the maintainer public keyring.
You can manage that trust root explicitly:
The default trust root is keys/maintainers.gpg; override it with
[release.signing].trust_root or --maintainers-gpg.
Add optional CI jobs and checks when the project needs them:
--with-msrv requires package.rust-version.
Cargo-runtime workflows include warm-cache steps by default: a ~/.cargo/bin
cache keyed by the generated workflow files, plus Swatinem/rust-cache@v2 for
Cargo registry and target state. Optional tool installs use command -v ... || cargo install ... --locked so a cache hit skips the download while a cache miss
still installs the required binary. Nix-runtime workflows skip these Cargo
caches and rely on the runner's Nix store and binary cache behavior.
Forgejo + Nix artifact workflows can also publish a Homebrew tap:
--with-homebrew is Forgejo + Nix only and implies --with-artifacts. The
project workflow must stage each enabled platform archive under
release/{name}-{version}-{arch}-{os}.tar.gz before the Homebrew step runs;
the generated step verifies those files exist but does not build project-shaped
tarballs itself.
Homebrew automation
Homebrew tap publishing tends to grow a lot of release-CI boilerplate. simit
keeps the tap metadata in project config, bootstraps the tap once, and
generates the Forgejo release step from that same config.
[]
= "https://codeberg.org/caniko/homebrew-foo.git"
= "caniko/foo"
= ["foo", "foo-ui"]
= "Cross-platform foo manager"
= "https://foo.example.com"
= "GPL-3.0-only"
= "foo-{version}-{arch}-{os}.tar.gz"
[]
# All four platforms are enabled by default. Override here if needed:
# linux_arm = false
Bootstrap the tap repo once with a placeholder formula:
# prints the next-step git commit and push hints
Wire the release workflow from the project repo:
For local inspection and iteration, render the formula or bump a checked-out tap using release archives:
rs-modde is the worked example for this flow: its release CI publishes
modde and modde-ui to caniko/homebrew-modde from the generated Homebrew
step.
Windows packaging
simit can render and publish Windows packages for Chocolatey and Scoop from
the same project metadata used by release artifacts. Declare the package
surface in project config:
[]
= "foo"
= "Foo"
= "Example Maintainers"
= "Cross-platform foo manager"
= "https://foo.example.com"
= "caniko/foo"
= "foo-{version}-{arch}-windows.zip"
[]
= "foo"
= "https://codeberg.org/caniko/scoop-foo.git"
= "caniko/foo"
= ["foo"]
= "foo-{version}-{arch}-windows.zip"
[]
# x64 and arm64 are enabled by default. Override here if needed:
# arm64 = false
Bootstrap the package repositories once:
Wire Windows publishing into tagged release CI:
--with-chocolatey and --with-scoop imply --with-artifacts. GitHub uses
windows-latest by default. Forgejo uses [ci.defaults.forgejo].windows from
the simit user config unless --windows-runner overrides it. Generated workflows read
secrets.chocolatey_api_key for Chocolatey pushes and
secrets.scoop_bucket_token for Scoop bucket pushes.
For local inspection and iteration:
Project config
Projects may opt in to stable simit settings with exactly one project config source. Supported sources are:
simit.tomlat the Cargo workspace root.[workspace.metadata.simit]or[package.metadata.simit]in rootCargo.toml.outputs.simitConfiginflake.nix.
All sources use the same section names: [flake], [ci], [homebrew],
[chocolatey], and [scoop].
For each Homebrew setting, resolution order is: CLI flag, simit project config,
Cargo package metadata, then an error. tap_url and download_repo have no
Cargo metadata fallback, so they must be set by a flag or in project config.
[]
= "https://codeberg.org/caniko/homebrew-mythos.git"
= "caniko/mythos"
= ["mythos", "mythos-ui"]
# description, homepage, license, and name default from Cargo.toml when unset.
[]
= false # Override: do not publish aarch64-linux.
Chocolatey and Scoop use the same resolution order. Their download_repo
fields must be OWNER/REPO, and Scoop also requires bucket_url.
Projects with custom flakes can keep their own Nix inputs and outputs while
letting simit manage formatter/pre-commit hooks. Set [flake].mode = "custom"
to make simit init flake --check validate simit's required wiring
semantically instead of comparing against the canonical flake template:
[]
= "custom"
= "toolchain.rustToolchain"
= "craneLib"
= "package"
[]
= ["default", "docs", "site"]
= ["default", "formatting", "clippy", "fmt", "nextest", "doc", "audit", "deny", "hm-module"]
= ["hmModules"]
Project CI can also declare stable workflow additions without hand-editing the generated YAML:
[]
= [
"apt-get update && apt-get install -y --no-install-recommends postgresql-client",
]
= { = "${{ secrets.SKILLNET_TEST_PG_URL }}" }
= ["SKILLNET_TEST_PG_URL", "CRATES_IO_API_TOKEN"]
User config
User config is intentionally separate from project config. It stores local infrastructure such as runner labels, while repositories stay portable.
[]
= "forgejo"
= ["atlas"]
= "linux"
= "x86_64"
= ["cargo", "nix"]
= true
[]
= "forgejo"
= ["windows-atlas"]
= "windows"
= "x86_64"
= ["cargo"]
[]
= "atlas"
= "atlas"
= "atlas"
= "windows_atlas"
Each default names a runner from [ci.runners]. The selected runner must match
the requested platform, operating system, and runtime before simit writes a
workflow. GitHub keeps portable built-in fallbacks (ubuntu-latest and
windows-latest) when user config does not override them.
Project config in Cargo metadata nests the same project schema under
metadata.simit:
[]
= "https://codeberg.org/caniko/homebrew-mythos.git"
= "caniko/mythos"
Flake config exports the same schema as JSON-compatible Nix data:
{
outputs = {self, simit, ...}: {
simitConfig = simit.lib.mkSimitConfig {
homebrew = {
tap_url = "https://codeberg.org/caniko/homebrew-mythos.git";
download_repo = "caniko/mythos";
};
flake = {
mode = "custom";
toolchain_binding = "toolchain.rustToolchain";
expected_outputs.checks = ["hm-module"];
expected_outputs.top_level = ["hmModules"];
};
ci = {
extra_setup = ["echo project setup"];
extra_env.SKILLNET_TEST_PG_URL = "\${{ secrets.SKILLNET_TEST_PG_URL }}";
};
};
};
}
Flake and hook wiring
Generate a canonical Rust crane flake plus formatter and pre-commit hook definitions:
This writes flake.nix, nix/treefmt.nix, and nix/pre-commit.nix,
detects Rust, Nix, uv-based Python, TOML, YAML, and Markdown files, and wires
treefmt-nix and cachix/git-hooks.nix. Existing flake.nix files are
patched only when simit can find safe anchors; otherwise, use --print and
apply the generated wiring manually.
In custom flake mode, simit init flake writes only nix/treefmt.nix and
nix/pre-commit.nix; the repository-owned flake.nix is left intact. The
check mode requires treefmt/git-hooks inputs, the treefmtEval and
pre-commit-check bindings, formatter/check/dev-shell hook wiring, and any
configured expected outputs. This supports flakes based on helpers such as
rs-harbor without requiring simit to render every project-specific output.
Preview the generated files without writing them:
Check committed flake and hook files in CI:
Shell integration
Generate shell completions or a manpage:
Release checklist
Before publishing a release, make sure CHANGELOG.md has the intended
## [Unreleased] entries. You can validate them explicitly with
simit changelog check, then run:
The crates.io publish workflow runs when the release tag is pushed and requires
CRATES_IO_API_TOKEN. It also requires keys/maintainers.gpg, which
simit init ci and simit release trust init generate from the configured
release signing key.
If that tag-triggered workflow fails after the tag has already been pushed, commit the fix and rerun the release pipeline with:
License
simit is licensed under the MIT License. See LICENSE.