Getting started

This guide adds Sacho to a repository, writes one changelog fragment, and previews the next release.

Install Sacho

The recommended installation uses mise's GitHub backend:

mise use -g github:dahlia/sacho

npm installs the same prebuilt binary:

npm install -g @sacho/sacho

Cargo can build the published crate from source:

cargo install sacho

Run sacho --version to confirm that the executable is on your PATH.

Initialize a repository

From the repository root, run:

sacho init

Sacho creates sacho.toml, changes.d/, and CHANGES.md. In a Git repository it also registers merge drivers in .gitattributes and the local Git config. Interactive setup can infer issue links from the repository remote and offer to install commit hooks.

Use sacho init --interactive to ask the setup questions even when automatic detection would otherwise be enough. For scripts, --no-interactive prevents prompts.

Set the version you are preparing:

sacho next 1.2.0

Write a fragment

Create a fragment named after the change:

sacho add clear-function

The command prints a path such as changes.d/clear-function.md. The new file contains an empty list item. Complete it with prose for the people who use the project:

 -  Added `clear()` to remove every entry at once.

Describe the released behavior. Leave out private type names, refactoring details, and intermediate designs that users will never encounter.

Format and inspect the release

Format the fragments and generated changelog:

sacho fmt

Print the release as Sacho would compile it:

sacho preview

Finally, check the repository:

sacho check

Commit the fragment with the source change. It will now follow that change through merges, rebases, cherry-picks, and reverts.

Continue with Everyday workflow, or read How Sacho fits together for the underlying model.