semtag — Semantic Versioning for Git

semtag

Semantic versioning for Git.

Auto-detects the correct bump level from Go API changes. Supports multi-module workspaces. No framework dependencies.

$ semtag
● on default branch (main)
● no uncommitted changes
● no remote changes
● no unpushed changes
● no new remote tags
● detected: 1 breaking, 2 compatible → major bump
● bump tag v1.2.3 => v2.0.0
● tag v2.0.0 created
● tag v2.0.0 pushed

Install

Go

go install github.com/flaticols/semtag@latest

Binary

GitHub Releases

Usage

semtag Auto-detect bump level from API diff

semtag patch Explicit patch bump — 1.2.3 → 1.2.4

semtag major Major bump — 1.2.3 → 2.0.0

semtag minor pkg/semver Multi-module bump — pkg/semver/v1.0.0 → pkg/semver/v1.1.0

semtag --dry-run Preview without creating or pushing tags

semtag undo Remove latest tag with interactive confirmation

semtag diff v1.0.0 Compare Go API surface against HEAD

semtag --json patch Pure JSON output, no log messages

semtag llm Print compact LLM-friendly help in XML format

Flags

-n, --dry-runPreview changes, skip tag creation

--jsonStructured JSON only to stdout

--prefixTag prefix for multi-module repos

-r, --repoRepository path

-l, --localSkip remote operations

-b, --braveSkip all checks and confirmations

--no-colorDisable colors

--no-ttyDisable interactive prompts

--verboseDebug output

Features

Auto Bump Detection

Runs API diff against the last tag to determine if you need a major, minor, or patch bump. No arguments required.

Workspace Detection

Reads go.work, verifies go.mod in each module, and prompts you to select which module to bump.

API Diff

Compares Go API surfaces between any two refs using temporary worktrees. Your working tree is never touched.

Dry Run

Preview what would happen without creating or pushing tags. Combine with --json for scripted workflows.

JSON Output

Clean structured JSON to stdout. No log messages, no styled output — just data for pipes and scripts.

Pre-flight Checks

Validates branch, uncommitted changes, remote sync, and unfetched tags before any tag operation.

Multi-Module

Prefix tags like pkg/semver/v1.2.3 for Go monorepos. Specify via flag, positional arg, or let it auto-detect.

TTY Aware

Detects terminal capabilities at startup. Colors, spinners, and prompts degrade gracefully to plain text.

LLM Help

semtag llm prints a compact XML summary of all commands, flags, JSON shapes, and behavior — designed for pasting into an AI context.

Minimal

No CLI framework: stdlib flag, slog, os/exec. No cobra, no viper. External deps: x/tools for API diff, flaticols/server for semver.

Examples

API Diff

$ semtag diff v0.0.6 v0.0.7
● comparing API: v0.0.6 -> v0.0.7

github.com/flaticols/semtag/semver
  Incompatible changes:
    - removed: ParseStrict
  Compatible changes:
    + added: ExpandPartialVersion
    + added: ParseConstraintSet

● summary: 1 breaking, 2 compatible
● suggested bump: major

JSON Output

$ semtag --json --brave patch
{"previous":"v1.2.3","version":"v1.2.4","pushed":true,"dry_run":false}

$ semtag --json --dry-run --brave
{"previous":"v1.2.3","version":"v2.0.0","pushed":false,"dry_run":true}

Multi-Module Workspace

$ semtag minor pkg/semver
● on default branch (main)
● no uncommitted changes
● no remote changes
● bump tag pkg/semver/v1.0.0 => pkg/semver/v1.1.0
● tag pkg/semver/v1.1.0 created
● tag pkg/semver/v1.1.0 pushed

Dry Run

$ semtag --dry-run
● on default branch (main)
● no uncommitted changes
● detected: 1 breaking → major bump
● bump tag v1.2.3 => v2.0.0
● dry-run: would create tag v2.0.0