Formats drift
v1.2.3, release-1.2.3, and final end up together. Soon nobody knows which tag is a real release.
Why Tagsmith
Tags are small—until release day makes them a risk.
Manual names, mixed formats, and an unclear tag history leave CI, release notes, and collaborators without a common source of truth.
Version order is guessed
Backfilling history or working in parallel can create a tag below an existing version and break automation.
Problems surface too late
Without local inspection and validation, an invalid tag may be discovered only by CI or another developer after it is shared.
One safe path
Make the convention clear before choosing the next version.
Inspect the history
Start with list to sort tags semantically and flag mismatches, unparseable versions, and duplicates. Tagsmith never rewrites history automatically.
Establish intent
A clear SemVer history can continue. For mixed, ambiguous, or non-SemVer history, use init to define the team convention first.
Preview safely
Inspect again, then use next to calculate the next version. This step does not change the repository.
Create later
Creation validates the convention and known local history. Pushing to a remote is a separate, deliberate action controlled by the team workflow and off by default.
Start with one line
A clear convention can grow with your release rhythm.
SemVer, CalVer, and build numbers
SemVer is the default zero-configuration evaluation path. Once the convention is explicit, choose CalVer or a monotonically increasing build number when it fits the team better.
One tag line, then scale deliberately
Start with one tag line and one shared rule. Add multiple tag lines only when app, release, or other independent sequences truly need separation.
Let automation consume the result
--json gives CI and scripts Tagsmith's convention-evaluation result; surrounding automation remains responsible for what happens next.
Optional local workflow guardrails
Merge policy can help enforce repository conventions in local git workflows. It is not remote branch protection or server-side policy enforcement.
Keep artifacts and change intent aligned
A tag line can check its package.json version, while an inspectable commit policy explains patch, minor, or major recommendations. When needed, creation can enforce the same checks.
Adopt deliberately
After trying it, make the convention a team responsibility.
When the inspection matches your intent, use tagsmith init and commit the generated .tagsmith.json. The convention then belongs to the team, not one maintainer's habit.
Adoption step
$ npx @carllee1983/tagsmith init✓ Created .tagsmith.json
# Commit the team's explicit convention
$ git add .tagsmith.json