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

Without mise, npm, or Cargo, download the archive for your platform from GitHub Releases, then place sacho (sacho.exe on Windows) in a directory on your PATH.

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

Install the Agent Skill

Sacho ships an Agent Skill that helps AI coding agents like Claude Code drive the workflows in this guide: writing fragments, cutting releases, and forward-porting fixes.

In Claude Code, install it as a plugin from this repository:

/plugin marketplace add dahlia/sacho
/plugin install sacho@sacho

For other agents, install it with the skills CLI, which reads the skill straight from the repository:

npx skills add dahlia/sacho

Use -a claude-code to target one agent and -g to install it globally.

Projects that depend on the @sacho/sacho npm package instead get the skill bundled inside it, following the skills-npm layout. Run npx skills-npm setup once in such a project to link it into your agent on every install.

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. When CHANGES.md already exists, it can also offer level-three headings found across the changelog as section ids, then suggest fragment directories and source path globs for the selected sections. If two or more selected ids map to one unambiguous sibling package directory, Sacho offers to store them as one section pattern instead.

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

Import existing unreleased entries

Skip this step when the changelog has no current unreleased entries. Otherwise, run the import before creating any fragments:

sacho import-unreleased

The command reads the current Unreleased or Version X region, creates changes.d/imported-unreleased.md, and leaves released history unchanged. Repositories configured with sections receive one file in each populated section directory. A Version X heading also becomes the next-version value, so do not run sacho next separately unless the heading is Unreleased.

Sacho shows a diff when compiling the imported fragments would normalize the region. Confirm it in a terminal, or use --force after reviewing the same change in a noninteractive workflow. --force does not permit existing Markdown fragments or top-level prose, headings, and lists that fragments cannot represent.

If the import did not infer a version, 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.