- Parse git history and generate changelog.
- Calculate the next version based on semver and conventional commits.
- Parse changelog files and extract changes for a given version.
brew install release-tools/tap/sincego install github.com/release-tools/sinceChangelog - Parse and update changelog files.
Project - List the changes since the last release in the project repository, or determine the next semantic version based on those changes.
Config - Scaffold a config file for the tool.
Generates a new changelog based on an existing changelog file, adding a new release section using the commits since the last release, then prints it to stdout.
Usage:
since changelog generate [flags]
Flags:
-g, --git-repo string Path to git repository (default ".")
-h, --help help for generate
-o, --order-by string How to determine the latest tag (alphabetical|commit-date|semver)) (default "semver")
Global Flags:
-c, --changelog string Path to changelog file (default "CHANGELOG.md")
--output-file string Path to output file (otherwise stdout)
-l, --log-level string Log level (debug, info, warn, error, fatal, panic) (default "debug")
-q, --quiet Disable logging (useful for scripting)
Updates the existing changelog file with a new release section, using the commits since the last release.
Usage:
since changelog update [flags]
Flags:
-g, --git-repo string Path to git repository (default ".")
-h, --help help for update
-o, --order-by string How to determine the latest tag (alphabetical|commit-date|semver)) (default "semver")
Global Flags:
-c, --changelog string Path to changelog file (default "CHANGELOG.md")
-l, --log-level string Log level (debug, info, warn, error, fatal, panic) (default "debug")
-q, --quiet Disable logging (useful for scripting)
Extracts changes for a given version in a changelog file. If no version is specified, the most recent version is used.
Usage:
since changelog extract [flags]
Flags:
--header whether to include the version header in the output
-h, --help help for extract
-v, --version string Version to parse changelog for
Global Flags:
-c, --changelog string Path to changelog file (default "CHANGELOG.md")
--output-file string Path to output file (otherwise stdout)
-l, --log-level string Log level (debug, info, warn, error, fatal, panic) (default "debug")
-q, --quiet Disable logging (useful for scripting)
Initialises a new changelog file based on the specified git repository.
Usage:
since changelog init [flags]
Flags:
-g, --git-repo string Path to git repository (default ".")
-h, --help help for init
-o, --order-by string How to determine the latest tag (alphabetical|commit-date|semver)) (default "semver")
--unique De-duplicate commit messages (default true)
Global Flags:
-c, --changelog string Path to changelog file (default "CHANGELOG.md")
--output-file string Path to output file (otherwise stdout)
-l, --log-level string Log level (debug, info, warn, error, fatal, panic) (default "debug")
-q, --quiet Disable logging (useful for scripting)
Reads the commit history for the current git repository, starting from the most recent tag. Lists the commits categorised by their type.
Usage:
since project changes [flags]
Flags:
-h, --help help for changes
Global Flags:
-g, --git-repo string Path to git repository (default ".")
-l, --log-level string Log level (debug, info, warn, error, fatal, panic) (default "debug")
-o, --order-by string How to determine the latest tag (alphabetical|commit-date|semver)) (default "semver")
-q, --quiet Disable logging (useful for scripting)
-t, --tag string Include commits after this tag
Reads the commit history for the current git repository, starting from the most recent tag. Returns the next semantic version based on the changes.
Changes influence the version according to conventional commits
Usage:
since project version [flags]
Flags:
-c, --current Just print the current version
-h, --help help for version
Global Flags:
-g, --git-repo string Path to git repository (default ".")
-l, --log-level string Log level (debug, info, warn, error, fatal, panic) (default "debug")
-o, --order-by string How to determine the latest tag (alphabetical|commit-date|semver)) (default "semver")
-q, --quiet Disable logging (useful for scripting)
-t, --tag string Include commits after this tag
Generates a new changelog based on an existing changelog file, using the commits since the last release.
The changelog is then committed and a new tag is created with the new version.
Usage:
since project release [flags]
Flags:
-c, --changelog string Path to changelog file (default "CHANGELOG.md")
-h, --help help for release
Global Flags:
-g, --git-repo string Path to git repository (default ".")
-l, --log-level string Log level (debug, info, warn, error, fatal, panic) (default "debug")
-o, --order-by string How to determine the latest tag (alphabetical|commit-date|semver)) (default "semver")
-q, --quiet Disable logging (useful for scripting)
-t, --tag string Include commits after this tag
Creates a new since.yaml config file, pre-populated with commented
examples for branch requirements, pre/post hook scripts, and commit
exclusions. If a config file already exists (since.yaml or since.yml),
the command fails unless --force is set.
Usage:
since init [flags]
Flags:
-f, --force Overwrite an existing config file
-h, --help help for init
-o, --output string Directory to write the config file to (default: current directory)
Global Flags:
-l, --log-level string Log level (debug, info, warn, error, fatal, panic) (default "debug")
-q, --quiet Disable logging (useful for scripting)
You can also use a since.yaml file to configure the tool. This file should be placed in the root of your project repository. A since.yml file is also recognised; if both are present, since.yaml takes precedence.
The quickest way to start is since init, which drops a fully commented example config into your project. Uncomment the bits you need.
# require us to be on the main branch
requireBranch: main
ignore:
- "commit message with this string will be ignored"
before:
- script: |
# run some tests before the release
# e.g. npm test
after:
- script: |
# any post-release steps
# e.g. npm publishThis repository ships an Agent Skill
(skills/since/SKILL.md) that teaches an AI coding agent how to perform
releases, generate changelogs, work out the next version, and scaffold a
since.yaml — driving the commands documented above.
The skill works with Claude Code, Cursor, Codex, OpenCode and other agents that support the open skills format. Install it with a single command:
npx skills add release-tools/sinceThat auto-discovers the skill in this repo. Add -g to install it globally
(user directory) rather than into the current project, or -a to target a
specific agent, for example:
npx skills add release-tools/since -g -a claude-codeThis repository also acts as a Claude Code plugin marketplace, so you can install the same skill (plus future commands) as a plugin:
/plugin marketplace add release-tools/since
/plugin install since@release-tools
Once installed, ask the agent to "perform a release", "work out the next version", or "scaffold a since config", and it will use the tool accordingly.
You can use since with GitHub Actions to automate the release process.
name: Release
on:
push:
tags:
- "v*.*.*"
jobs:
release:
runs-on: ubuntu-latest
permissions:
contents: write
steps:
- uses: actions/checkout@v4
- name: Extract entries from most recent release in CHANGELOG.md
uses: release-tools/since@main
with:
output-file: release-changes.md
- name: Create release
uses: actions/github-script@v9
with:
script: |
const fs = require('fs');
const tag = context.ref.replace('refs/tags/', '');
await github.rest.repos.createRelease({
owner: context.repo.owner,
repo: context.repo.repo,
tag_name: tag,
name: tag,
body: fs.readFileSync('release-changes.md', 'utf8'),
draft: false,
prerelease: false,
});