Installation

Via cargo

cargo install --locked tagit

Example Workflow

Important

tagit currently uses only 1.2.3 tags for versions, not v1.2.3. This is highly unlikely to change, except for maybe the major-only v1 in addition to 1, because of compatibility (some tools misunderstand 1 as short hash)

Important

You need upstream remote set up to use anything with tagit.

Init

tagit changelog init

Make changes

Note

tagit isn’t used in this section, but it later uses the changes we make here.

edit stuff

vim src/somefile.rs

mention that in the changelog within the [Unreleased] section

vim CHANGELOG.md

bump the version; if you’re on 1.2.3, bump to 1.2.4-a.0; if you’re on 1.2.4-a.0, bump to 1.2.4-a.1; and so on…

vim Cargo.toml

update Cargo.lock

cargo clippy

commit (or skip directly to the next section)

git add src/somefile.rs CHANGELOG.md Cargo.toml Cargo.lock
# or just git add .
git commit -m "..." # write what changed instead of `...`

Prepare release

if necessary, bump to a non-prerelease version; if you’re on 1.2.4-a.1, then bump to 1.2.4

vim Cargo.toml
cargo clippy

re-arrange the changelog

tagit changelog

commit

git add CHANGELOG.md Cargo.toml Cargo.lock
# or just git add .
git commit -m "..." # instead of `...`, write either what changed or release version
git push

update tags

tagit tag

assuming you’ve set up CI with https://codeberg.org/parrrate/forgejo-release, the changelog will show up in the release

Commands

• tagit tag
• tagit changelog
• tagit diff
• tagit sub

tagit tag

Updates repository tags in accordance with workspace’s package manifests.

Normal way to run it is:

tagit tag

Caution

By default, this will tag all packages that it can find. See tagit.skip config.

If you cannot enable commit signing on your system, you’ll have to actively opt out:

tagit tag --sign=false

Note

tagit forces signing by default to avoid accidentally missing a signature. This is because of how parrrate uses tagit internally.

To check what tagit tag is going to do without applying any changes, use --dry-run:

tagit tag --dry-run

Retagging

By default, all stable releases (ones without the pre-release segment), when a new tag is created for them, also update related Rust-style SemVer tags:

• If --no-retag is used, no extra tags are created or updated.
• If tag without +metadata doesn’t exist, it gets created.
• If --total-order is used, tag without +metadata gets updated.
• A.B.C with A greater than or equal to 1 updates A.B and A
• 0.B.C with B greater than or equal to 1 updates 0.B

Changelog

When a new tag is created, its message is pulled from the related section of the CHANGELOG.md.

Warning

If anything goes wrong at this step, it’s possible that it’ll get silently ignored.

tagit changelog

Rearranges the CHANGELOG.md file in all workspace members:

tagit changelog

Tip

It’s recommended to stage your manual changes before auto-rearrangement, to ensure tagit changelog is non-destructive.

To check that the changelog is valid without applying any changes, use --dry-run:

tagit tag --dry-run

Just like with tagit tag, versions are parsed from package manifests.

Changelog format

We use https://keepachangelog.com/en/1.1.0/ as the basis.

# Changelog

## [Unreleased]

### Added

- (feature)

- (feature)

## [1.0.1]

### Added

- (feature)

### Changed

- (behaviour change)

### Deprecated

- (something planned to be removed)

### Removed

- (something removed)

### Fixed

- (fix)

### Security

- (fix)

## [1.0.0]

(base version)

[unreleased]: (base)/compare/(tag_prefix)1.0.1...HEAD
[1.0.1]: (base)/compare/(tag_prefix)1.0.0...(tag_prefix)1.0.1
[1.0.0]: (base)/releases/tag/(tag_prefix)1.0.0

Important

Deviations from the format usually lead to errors. We don’t try to correct them.

Language Support

Rust (cargo) support

provided by tagit-workspace-cargo

Workspaces

Supported.

Versioning

Uses versions from Cargo.toml as is.

Config

Optional section in Cargo.toml:

[package.metadata.tagit]
skip = false # or `true`; optional
skip_retag = false # or `true`; optional

Diff

Presently, only includes src and Cargo.toml.