rustytag 1.0.21

A semantic version management tool built on Git tags.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101

---
name: rustytag
description: Manage semantic versions from Git tags with RustyTag. Use when inspecting versions, creating patch/minor/major tags, enforcing tag prefixes such as v for Go modules, configuring user or repository defaults, synchronizing tags, or creating GitHub releases.
---

# RustyTag

Treat Git tags as the version source of truth. Run RustyTag inside a Git repository unless using `init`.

## Inspect the version

Use human-readable output interactively:

```sh
rustytag show
```

Use stable machine-readable output in scripts and Makefiles:

```sh
rustytag show --quiet  # one version value, for example v0.1.0
rustytag show --json   # version, branch, commit_count, repository_url, rustytag_version
```

Do not parse the default report. Do not combine `--quiet` and `--json`. In a repository without tags, the initial semantic version is `0.1.0`, with any configured prefix applied.

## Configure RustyTag

Load configuration in this order, with later layers overriding earlier ones:

1. User configuration: `~/.rustytag.json`
2. Repository configuration: `./.rustytag.json`
3. CLI or environment overrides for the current execution

Set common values:

```sh
rustytag config --set GITHUB_TOKEN=TOKEN       # user layer by default
rustytag config --set VERSION_PREFIX=v         # repository layer by default
rustytag config --set VERSION_PREFIX=v --global
rustytag config --set GITHUB_TOKEN=TOKEN --local
rustytag config                                # show user, repository, and effective values
```

Use `--global` to write `~/.rustytag.json` and `--local` to write `./.rustytag.json`. When RustyTag detects a prefix in an existing tag, persist it to the repository configuration automatically.

## Create version tags

Commit product changes before bumping. Then bump from the latest semantic tag:

```sh
rustytag patch  # 1.0.0 -> 1.0.1
rustytag minor  # 1.0.0 -> 1.1.0
rustytag major  # 1.0.0 -> 2.0.0
```

Set an exact version when required:

```sh
rustytag patch --version 1.2.3
rustytag patch -V v0.1.0
```

For a Go repository, configure `v` and explicitly create the first standard Go tag:

```sh
rustytag config --set VERSION_PREFIX=v
rustytag patch -V v0.1.0
```

Subsequent bumps preserve the repository prefix. RustyTag updates detected project version files, generates `CHANGELOG.md`, creates a release commit, and creates an annotated tag. Verify that unrelated work is committed first so the tagged commit and build remain clean.

## Publish and synchronize

After creating a tag, verify and push the release commit and tags:

```sh
git status --short
git tag --points-at HEAD
git push --follow-tags origin main
```

Manage tag synchronization and GitHub releases:

```sh
rustytag sync
rustytag reset
rustytag release --list
rustytag release --tag v1.2.3
```

Configure `GITHUB_TOKEN` before creating a GitHub release. Treat `reset`, tag creation, pushes, and releases as state-changing operations; inspect repository status and remotes before running them.

## Command reference

- `init` — Initialize a Git repository.
- `patch`, `minor`, `major` — Create the next or an explicitly specified semantic version.
- `show` — Show the effective current version and project information.
- `config` — Read or update layered configuration.
- `sync`, `reset` — Synchronize or reset tags against the remote.
- `release` — List or create GitHub releases.