Overview
These functions help you work with Git tags that follow the Semantic Versioning (SemVer) specification. They allow you to filter and identify tags that conform to the MAJOR.MINOR.PATCH format.
Retrieves all Git tags from the repository and filters only those that follow a Semantic Version (SemVer) format.
Syntax
function getSemverTags(): Promise<string[]>
Returns
A promise that resolves to an array of SemVer-compliant tag names.
Examples
const semverTags = await getSemverTags()
console.log(semverTags)
// ['v1.0.0', 'v1.1.0', '2.0.0']
Find the latest SemVer tag
import semver from 'semver'
const tags = await getSemverTags()
const versions = tags.map(tag => tag.replace(/^v/, ''))
const latest = semver.maxSatisfying(versions, '*')
console.log('Latest version:', latest)
Filter pre-release versions
const tags = await getSemverTags()
const stableVersions = tags.filter(tag => !tag.includes('-'))
const preReleases = tags.filter(tag => tag.includes('-'))
console.log('Stable:', stableVersions)
console.log('Pre-releases:', preReleases)
How it works
Internally, getSemverTags() performs two operations:
- Fetches all tags using
getTags()
- Filters them using
isSemverTag()
isSemverTag()
Checks whether a given string conforms to a Semantic Version (SemVer) tag format.
Syntax
function isSemverTag(tag: string): boolean
Parameters
Returns
Returns true if the tag matches a SemVer-compatible format, otherwise false.
Examples
isSemverTag("v1.0.0") // true
isSemverTag("1.2.3") // true
isSemverTag("1.2.3-alpha") // true
isSemverTag("v2.0.0-beta.1") // true
isSemverTag("v1") // false (incomplete version)
isSemverTag("version-1.0.0") // false (invalid prefix)
isSemverTag("1.0") // false (missing patch version)
isSemverTag("release-1") // false (not a version)
import { getTags, isSemverTag } from 'usegit'
const allTags = await getTags()
const semverTags = allTags.filter(isSemverTag)
const otherTags = allTags.filter(tag => !isSemverTag(tag))
console.log('SemVer tags:', semverTags)
console.log('Other tags:', otherTags)
Validate tag before creation
import { isSemverTag, createTag } from 'usegit'
const newTag = "v1.2.3"
if (isSemverTag(newTag)) {
await createTag(newTag)
console.log(`Created SemVer tag: ${newTag}`)
} else {
console.error(`Invalid SemVer format: ${newTag}`)
}
What it supports
- Optional
v prefix: Both v1.2.3 and 1.2.3 are valid
- Standard format:
MAJOR.MINOR.PATCH versions (e.g., 1.0.0)
- Pre-release identifiers: Optional
-alpha, -beta.1, etc. (e.g., 1.0.0-rc.1)
What it does NOT validate
- Build metadata: The
+build suffix is not validated (kept intentionally lightweight)
- Strict SemVer edge cases: Some strict SemVer rules are not enforced to keep the function simple and fast
Implementation
The function uses a regular expression to match SemVer patterns:
return /^v?\d+\.\d+\.\d+(-[\w.-]+)?$/.test(tag)
^v? - Optional v prefix\d+\.\d+\.\d+ - Three numeric segments separated by dots(-[\w.-]+)?$ - Optional pre-release suffix starting with -
Common Use Cases
Automated versioning
import { getSemverTags, createTag } from 'usegit'
import semver from 'semver'
const tags = await getSemverTags()
const versions = tags.map(tag => tag.replace(/^v/, ''))
const latest = semver.maxSatisfying(versions, '*') || '0.0.0'
const nextVersion = semver.inc(latest, 'patch')
await createTag(`v${nextVersion}`)
console.log(`Created new version: v${nextVersion}`)
Release validation
import { hasTag, isSemverTag } from 'usegit'
async function validateRelease(version: string) {
if (!isSemverTag(version)) {
throw new Error(`Invalid SemVer format: ${version}`)
}
if (await hasTag(version)) {
throw new Error(`Tag already exists: ${version}`)
}
console.log(`Version ${version} is valid and available`)
}
await validateRelease('v2.0.0')
Generate changelog
import { getSemverTags } from 'usegit'
const versions = await getSemverTags()
const sortedVersions = versions
.map(v => v.replace(/^v/, ''))
.sort(semver.rcompare)
.map(v => `v${v}`)
console.log('Release history:')
sortedVersions.forEach(version => {
console.log(`- ${version}`)
})