Updraft

Updraft is an interactive release-note and changelog CLI for Git repositories. It keeps CHANGELOG.md current, supports reusable project registration, collects change notes during development, calculates SemVer releases, and can create annotated Git tags after a release is committed.

Highlights

Changelog Workflow

• Creates a Keep a Changelog-style CHANGELOG.md for initialized repositories
• Adds structured notes under Unreleased while work is in progress
• Promotes drafts into versioned releases with a confirmation preview
• Supports Added, Changed, Deprecated, Removed, Fixed, and Security by default
• Allows repository-specific categories and required release-note sections

Version Management

• Accepts any valid semantic version, including prereleases
• Calculates major, minor, and patch releases
• Supports alpha, beta, and release-candidate channels
• Combines release levels and prerelease channels, such as --minor --rc
• Finalizes a prerelease with --patch, for example 1.4.1-rc.2 to 1.4.1

Project Registry

• Registers named repositories in the user configuration directory
• Lets you work from anywhere with commands like updraft myproject bump
• Provides an interactive project picker with updraft bump
• Supports bulk registration of initialized direct child repositories

Git Integration

• Shows repository cleanliness and the latest Git tag in project status
• Uses advisory per-project locks to prevent conflicting Updraft operations
• Creates annotated vVERSION tags for existing, committed changelog releases
• Does not create commits, push branches, or change package manifests

Table of Contents

• Installation
• Quick Start
• Commands
• Configuration
• Git Tags
• Shell Completion
• Behavior and Safety
• Development
• Contributing

Installation

Requirements

• Rust and Cargo
• Git

Install From Source

git clone https://github.com/sudoserver819/updraft.git
cd updraft
cargo install --path .

After the crate is published, installation will also be available with:

cargo install updraft-cli

Quick Start

Initialize Updraft from the root of a Git repository:

cd /path/to/repository
updraft init

This creates .updraft.toml and CHANGELOG.md. Register the repository under a short name:

updraft project add myproject /path/to/repository

Create an Unreleased draft note during development:

updraft myproject draft

Create the release when the work is ready:

updraft myproject bump

Updraft previews the release and asks for confirmation before modifying the changelog.

Commands

Repository Setup

updraft init
updraft project add myproject /path/to/repository
updraft project list
updraft project remove myproject

Project registrations are stored in $XDG_CONFIG_HOME/updraft/projects.toml, or ~/.config/updraft/projects.toml when XDG_CONFIG_HOME is not set.

Bulk Project Registration

Register every initialized direct child repository in a parent directory:

updraft project add '*' ~/Projects

Quote the asterisk so your shell passes it to Updraft. Each direct child folder becomes a project name. Uninitialized folders and duplicate names are reported and skipped. The scan is not recursive.

Drafts and Status

Draft notes stay below ## [Unreleased] until a release promotes them:

updraft myproject draft
updraft myproject draft --note 'Added:Project picker' --yes
updraft myproject status
updraft status myproject

Status displays the repository path, changelog path, latest release, latest tag, Unreleased note count, and whether Git has uncommitted changes.

Releases

Interactive release selection presents patch, minor, major, alpha, beta, release-candidate, and manual-version choices:

updraft myproject bump
updraft bump

Use explicit flags for scripts and CI:

updraft myproject bump --version 1.2.0 --note 'Added:Shell completion' --yes
updraft myproject bump --minor --note 'Changed:New workflow' --yes
updraft myproject bump --patch --rc --note 'Fixed:Release candidate issue' --yes
updraft myproject bump --minor --beta --note 'Changed:Beta review' --yes
updraft myproject bump --major --alpha --note 'Added:Next generation API' --yes
updraft myproject bump --dry-run

--note accepts CATEGORY:TEXT and can be repeated. --yes skips confirmation and makes the command non-interactive when used with --version, --major, --minor, --patch, --alpha, --beta, or --rc.

Prerelease rules:

• Stable 1.4.0 with --alpha becomes 1.4.1-alpha.1.
• 1.4.1-beta.2 with --beta becomes 1.4.1-beta.3.
• 1.4.1-rc.2 with --patch becomes final 1.4.1.
• --minor --rc from 1.4.0 becomes 1.5.0-rc.1.

Configuration

updraft init creates .updraft.toml in the repository root:

[project]
name = "myproject"
changelog = "CHANGELOG.md"
categories = ["Added", "Changed", "Deprecated", "Removed", "Fixed", "Security"]
required_categories = []

You can replace the category list to match the project. Any category listed in required_categories must have at least one note before Updraft allows a release.

For safety, the changelog path must remain within the repository. Updraft rejects absolute paths and paths that escape using ...

Git Tags

After you commit the changelog release, create an annotated tag:

updraft myproject tag --version 1.2.0
updraft myproject tag --version 1.2.0 --message "Updraft 1.2.0"

This creates v1.2.0 at the current Git HEAD. Tagging is separate from bump because Updraft does not create commits; tagging immediately after a changelog edit would otherwise point at a commit that does not contain that edit.

Shell Completion

Generate completion scripts for Bash, Zsh, Fish, PowerShell, or Elvish:

updraft completions zsh > ~/.zfunc/_updraft
updraft completions bash > ~/.local/share/bash-completion/completions/updraft

Behavior and Safety

• Updraft only changes the configured changelog file.
• --dry-run previews a release without modifying files.
• Empty releases are rejected.
• Existing changelog versions and Git tags are never overwritten.
• Locks live in the user configuration directory, not in repositories, so status stays clean.
• Manual Unreleased content must use Updraft category headings and bullet items before Updraft can safely promote it.

Development

Project Layout

updraft/
├── src/
│   ├── lib.rs                 # Changelog, registry, Git, and configuration logic
│   └── main.rs                # CLI parsing and interactive workflows
├── .github/
│   ├── ISSUE_TEMPLATE/        # Bug report and feature request forms
│   ├── workflows/ci.yml       # Formatting, test, lint, and packaging checks
│   └── pull_request_template.md
├── Cargo.toml
├── README.md
├── LICENSE-MIT
└── LICENSE-APACHE

Quality Checks

cargo fmt --check
cargo test
cargo clippy -- -D warnings
cargo package --allow-dirty --list

Contributing

Issues and pull requests are welcome. Before opening a pull request:

• Keep behavior changes covered by focused tests.
• Run formatting, tests, and Clippy with warnings denied.
• Update command help and this README for user-visible changes.
• Keep changelog parsing conservative: avoid overwriting manual content that Updraft cannot interpret safely.

License

Licensed under either of:

• Apache License, Version 2.0
• MIT License

at your option.