git-versioning

git-versioning: structure-based version scheme

Adopt and operate a MAJOR.MINOR.PATCH version scheme that is computed locally at build time from the git commit graph. It needs no tags, CI, or tokens, and is deterministic — the same commit always yields the same version.

• MINOR = merge (MR/PR) count − MR_BASE → +1 per merge, resets patch to 0
• PATCH = direct main commits since the last merge (first-parent) → +1 per hotfix commit, 0 right after a merge
• MAJOR = MAJOR_BASE (a human-chosen milestone) + overflow carry (effectively never)

The number is a monotonically increasing build identifier pointing at "where in git this build sits." For the full rationale and the comparison to the standard, see references/versioning-policy.md.

When this scheme fits (decide first)

• ✅ Fits: internal/in-house products with no external consumers, on-demand shipping, QA needing to identify "which build is this," local determinism without CI/tokens.
• ❌ Does not fit: public npm/library/SDK where unknown external consumers judge upgrade safety from the number → prefer standard SemVer + Conventional Commits + semantic-release. Confirm with the user before init.

Usage

/git-versioning                  -- print the currently computed version (default)
/git-versioning status           -- same as above + breakdown (MAJOR/MINOR/PATCH basis)
/git-versioning init             -- install version.sh + version.conf + policy doc, then wire the build system
/git-versioning bump-major       -- manually bump the MAJOR milestone (edit version.conf)
/git-versioning release          -- guide tagging vX.Y.Z at an actual release
/git-versioning explain          -- explain what this scheme is and why it differs from the standard

Commands

status (default)

1. If scripts/version.sh exists at the project root, run it; otherwise run this skill's scripts/version.sh to print the version.
2. status also shows the breakdown — gather these git facts into a table:
   • git rev-list --merges --count HEAD → MINOR basis (merge count)
   • git rev-list --count --first-parent <last-merge>..HEAD → PATCH basis (commits since last merge)
   • MAJOR_BASE/MR_BASE from version.conf
   • git diff-index --quiet HEAD → dirty state
3. If version.sh is not installed yet, recommend init.

init

Install the scheme into the project. In order:

1. Fit check — review "When this scheme fits" above with the user. If it is a public library, recommend standard SemVer and stop.
2. Install scripts/version.sh — copy this skill's scripts/version.sh to the project's scripts/version.sh and chmod +x. If it already exists, confirm before overwriting.
3. Create version.conf (repo root) — defaults during 0.x:

   # Build version baseline — read by scripts/version.sh. Policy: <policy doc path chosen in step 4>
   MAJOR_BASE=0
   MR_BASE=0
   

4. Copy the policy doc — copy references/versioning-policy.md and substitute {PROJECT}. Decide the destination path by first detecting the project's doc convention: check CLAUDE.md for a doc-layout convention, or an existing docs folder (brain/, docs/, para/, …). The default is docs/versioning.md. But always check whether the destination is .gitignored — e.g. if docs/ is ignored, the policy doc never gets committed and silently disappears (verify with git check-ignore <path>). In that case place it on a tracked doc path (e.g. brain/areas/ when the project uses brain), and match the policy-path mention in the version.conf comment and the version.sh header accordingly.
5. Wire the build system — follow references/build-wiring.md to add version injection for the detected build system (Make/Go/Node/Python/generic). If several are present, ask the user which one to wire.
6. Verify — run bash scripts/version.sh and --dev, show that the values are sensible, and note that a non-shallow clone is required (it counts merges).

Outputs are created in the user's project (not inside the skill directory).

bump-major

Raise MAJOR for a milestone (rare). Procedure in versioning-policy.md §4:

1. Check the current merge count: git rev-list --merges --count <main-branch> (e.g. origin/main).
2. Edit version.conf — raise MAJOR_BASE to the target major and set MR_BASE to the merge count above → MINOR resets to 0.
3. Commit that change. Versions then start from <new-major>.0.x.
4. Confirm the result with version.sh.

release

Tag a QA-passed build as an actual release. Tags are created only at actual releases (policy §3):

1. Confirm the commit to ship is checked out and clean (no -dirty).
2. Compute that commit's version: bash scripts/version.sh → e.g. 0.21.0.
3. Create and push the same-named tag:

   git tag v0.21.0
   git push origin v0.21.0
   

4. The tag is only a marker — version computation does not read tags (§1). Do not pile up a tag per merge.

explain

Using versioning-policy.md as the basis, explain what this scheme is (§1) and how it differs from standard SemVer (§5), at the user's level. "Why not semantic-release" is §0.

Resources

File	Purpose
scripts/version.sh	Single source of version computation (language-agnostic, pure git). init copies it into the project.
references/versioning-policy.md	Policy, rationale, comparison to the standard. init copies it to the project's doc-convention path.
references/build-wiring.md	Make/Go/Node/Python/generic build-wiring recipes.

Notes

• Counts merges, so a non-shallow clone is required. CI/Docker should compute on the host and pass it in via build-arg (build-wiring.md Docker/CI section).
• GitHub squash-merge creates no merge commit, so MINOR does not advance — set PR merges to "merge commit" or read PATCH as the primary signal (policy §1).
• The build version carries no v (0.21.0); only release tags use vX.Y.Z.