Specification

GitCalVer specification — version format, algorithm, output formats, and edge cases

Version: 0.1 (draft)

Abstract

GitCalVer is a versioning scheme that derives version numbers deterministically from git history. Each first-parent commit on the default branch maps to a unique, strictly increasing version number based on the commit’s UTC date and its position within that day’s commits.

Version format

Base format

YYYYMMDD.N

Where:

• YYYYMMDD is the UTC date of the commit’s committer timestamp (4-digit year, 2-digit month, 2-digit day, no separators)
• N is a positive integer: the count of consecutive first-parent commits from this commit (inclusive) that share the same UTC committer date

Examples

A repository with 5 first-parent commits on main:

Commits e1–e3 share the date 2026-04-10. The latest (e3) is the 3rd consecutive commit with that date, so its version is 20260410.3.

When e4 is added on a new day, the count resets: 20260411.1.

Guarantees

1:1 mapping

Every first-parent commit on the default branch maps to exactly one version number. Every version number identifies exactly one commit.

Strictly increasing

Successive first-parent commits always produce strictly greater version numbers, under the prerequisite that committer dates on the first-parent chain are non-decreasing.

Proof. Within the same UTC date, each additional commit increments N, so versions are strictly increasing. Across a date boundary, YYYYMMDD increases. Since the first segment is compared first, YYYYMMDD₂.1 > YYYYMMDD₁.K for any K, so the version still strictly increases.

Prerequisite. Committer dates on the first-parent chain must be non-decreasing. This holds naturally when commits flow forward in time. History rewrites (rebase, filter-repo, force push) that produce decreasing committer dates void this guarantee. Implementations SHOULD validate this at the date boundary and report an error if violated.

Algorithm

To compute the version for HEAD:

1. Let DATE = the UTC committer date of HEAD, formatted as YYYYMMDD
2. Walk the first-parent chain starting from HEAD
3. Count consecutive commits whose UTC committer date equals DATE
4. Stop at the first commit with a different date
5. Let N = the count from step 3
6. The version is DATE.N

Committer date

GitCalVer uses the committer date, not the author date. The committer date reflects when a commit was applied to the branch (updated by rebase, amend, cherry-pick). The author date reflects original authorship and is preserved across history rewrites.

The committer date is chosen because it better represents the commit’s position in the branch’s timeline.

First-parent traversal

Only the first-parent chain is traversed. In a merge commit, the first parent is the branch being merged into (typically main). Commits from merged branches are not counted.

This means:

• Merge commits: the merge commit itself is counted; the merged branch’s commits are not
• Squash merges: the resulting commit counts as 1
• Fast-forward merges: the forwarded commits are counted individually

UTC

All dates are interpreted in UTC. A commit made at 23:00 local time in UTC+2 has a UTC time of 21:00 and uses that UTC date.

Git stores timestamps as Unix epoch seconds (1-second granularity) plus a timezone offset. The epoch seconds are inherently UTC-relative. The timezone offset is metadata and does not affect the UTC interpretation.

Dirty state

A version is dirty when either condition holds:

1. Dirty workspace: git status --porcelain produces any output (staged changes, unstaged changes, or untracked non-ignored files). Gitignored files do not make the workspace dirty.
2. Off default branch: HEAD is not on the default branch but is traceable to it (see Default branch). The version is computed from the merge-base commit.

Behavior

• By default, implementations MUST refuse to produce a version for a dirty state (exit with a non-zero status).
• A --dirty flag opts in to dirty versions (see Output Format).

Default branch

GitCalVer versions are derived from the default branch’s first-parent history.

Detection precedence

1. Explicit --branch BRANCH flag
2. git symbolic-ref refs/remotes/origin/HEAD (remote default)
3. Existence of origin/main, then origin/master
4. If no remote: existence of local main, then master
5. Error if no default branch can be determined

HEAD relationship

Implementations MUST check HEAD’s relationship to the default branch:

• On the default branch: HEAD is the branch tip or an ancestor of it (reachable via git merge-base --is-ancestor HEAD <branch-ref>). Produce a clean version (subject to workspace dirty checks). This includes detached HEAD pointing to a commit on the default branch, which is common in CI.
• Off the default branch but traceable: HEAD is not on the default branch but shares a common ancestor with it (git merge-base HEAD <branch-ref> succeeds). Treat as dirty: compute the version for the merge-base commit and apply dirty formatting. This covers feature branches and detached HEAD at non-default-branch commits.
• Not traceable: no common ancestor exists (e.g., orphan branches). Error.

Committer date validation

Implementations SHOULD validate that committer dates on the first-parent chain are non-decreasing. At minimum, when the counting walk (step 4 of the algorithm) encounters the first commit with a different date, that date SHOULD be checked:

• If it is later than HEAD’s date: error — committer dates are not non-decreasing. This indicates history was rewritten.
• If it is earlier or equal: valid.

This is a cheap check (O(1) at the boundary already visited). It does not validate the entire history but catches the most common violation.

In practice, standard git workflows (direct commits, merges, rebases) maintain the non-decreasing property. It can be violated by clock skew, explicit GIT_COMMITTER_DATE manipulation, or git rebase --committer-date-is-author-date with out-of-order author dates.

Output format

The version string is composed from a fixed base version plus optional prefix and dirty suffix, controlled by flags rather than named formats.

Base version

The base version is always YYYYMMDD.N. This is the invariant core of GitCalVer and cannot be changed.

Prefix

A --prefix PREFIX flag prepends a literal string to the version. The default prefix is empty.

Clean version: {prefix}YYYYMMDD.N

Common prefixes:

Dirty flags

By default, implementations MUST refuse to produce a version for a dirty workspace (exit with a non-zero status). The --dirty flag opts in to dirty versions.

Where HASH is the short commit hash (git rev-parse --short HEAD). The . before HASH is implicit and included automatically when the hash is present.

Dirty version (with hash): {prefix}YYYYMMDD.N{dirty}.HASH Dirty version (no hash): {prefix}YYYYMMDD.N{dirty}

Validation:

• --dirty "" is an error (dirty version would be indistinguishable from clean)
• --no-dirty-hash without --dirty is an error (no dirty mode to modify)
• --no-dirty and --dirty together: --no-dirty wins

Non-uniqueness

Dirty versions are not uniquely reversible. The 1:1 mapping guarantee applies only to clean versions. Multiple distinct states can produce the same dirty version string — for example, two dirty builds from the same commit with different uncommitted changes.

Dirty version sort order

In most ecosystems, the dirty version sorts before (lower than) the clean version. This is correct: a dirty build is not yet the release.

Exceptions:

• PEP 440: the + local segment sorts after the public version in local comparisons, but local versions are not permitted on PyPI
• Debian: the + suffix sorts after the base version

Ecosystem mapping

R/CRAN limitation: R version strings are sequences of at least two non-negative integers separated by . or - (Writing R Extensions). No alphabetic characters are permitted. YYYYMMDD.N is valid for clean builds. Dirty versions are not expressible in R-compatible version strings.

Haskell/Hackage limitation: PVP version strings are sequences of non-negative integers separated by . (PVP). No alphabetic characters are permitted. 0.YYYYMMDD.N is valid for clean builds. Dirty versions are not expressible in PVP-compatible version strings.

CFBundleVersion limitation: CFBundleVersion segments are numeric only. Dirty versions are not expressible.

HomeKit limitation: FirmwareRevision segments are numeric only (uint32). Dirty versions are not expressible.

Chrome extension limitation: Chrome extension versions (version) are 1–4 dot-separated integers, each between 0 and 65,535 (Chrome manifest version). Since YYYYMMDD values (e.g., 20260412) exceed 65,535, GitCalVer versions cannot be used as the version. However, Chrome’s version_name is a freeform string displayed to users instead of version when present. GitCalVer can be used as the version_name.

Firefox add-on limitation: Firefox add-on versions are 1–4 dot-separated integers, each up to 2,147,483,647 (WebExtensions manifest). YYYYMMDD.N is valid for clean builds. Dirty versions are not expressible since no alphabetic characters are permitted.

Alpine dirty-version note: Alpine uses pre-release suffixes (_alpha, _beta, _pre, _rc) that sort before the base version. --dirty _pre produces YYYYMMDD.N_pre, which apk correctly sorts below the clean version.

Nix dirty-version note: Nix’s builtins.compareVersions treats pre as a special component that sorts before an empty component. --dirty pre produces YYYYMMDD.Npre, which Nix correctly sorts below the clean version.

Mobile platform details

iOS/macOS (Apple):

• CFBundleShortVersionString (marketing version, shown to users): use --prefix 0. → 0.YYYYMMDD.N
• CFBundleVersion (build number, must be unique and increasing per App Store upload): use no prefix → YYYYMMDD.N. Each segment is a uint32 (max 4,294,967,295); 20260412 fits. The strictly-increasing guarantee satisfies TestFlight and App Store Connect requirements.

Android:

• versionName (displayed to users): any string → YYYYMMDD.N works
• versionCode (integer, must increase, Int32 max 2,147,483,647): cannot use YYYYMMDD.N directly since it requires a single integer. Derive as YYYYMMDD * 100 + N → e.g., 2026041203. This fits in Int32 and provides strictly-increasing values, but limits N to 99 per day. For most projects this is more than sufficient.

HomeKit:

• FirmwareRevision characteristic: format is x[.y[.z]] where each segment is a uint32. YYYYMMDD.N (two segments) is valid and 20260412 fits within uint32. The value must change after every firmware update, which GitCalVer guarantees.

Numeric limits

The YYYYMMDD segment (e.g., 20260412) must fit within each ecosystem’s numeric constraints:

Shallow clones

GitCalVer works with shallow clones as long as the clone includes all first-parent commits for the current UTC date. If the clone is too shallow (the oldest commit in the walked history shares HEAD’s date), the count may be incomplete. Implementations SHOULD detect this and warn.

A safe shallow clone depth for GitCalVer is any depth that includes at least one commit from the previous UTC date, for example:

git clone --shallow-since=yesterday

References