@hyperfrontend/versioning/git/modelsmodels
Plain-data git models for commits, tags, and refs, with factories and small predicates.
GitCommit, GitRef, and GitTag are the structured shapes consumed by every other git module. Factories (createGitCommit, createGitRef, createLightweightTag, createAnnotatedTag) produce instances from raw fields. Predicates (isSameCommit, isMergeCommit, isRootCommit, isBranchRef, isTagRef, isRemoteRef, isHeadRef) and accessors (getShortHash, extractScope, extractType) cover the common questions consumers ask of these models without having to re-derive the answers from the raw git output.
API Reference§
ƒ Functions
Builds a full reference name from type and name.
Parameters
| Name | Type | Description |
|---|---|---|
§type | GitRefType | Reference type |
§name | string | Reference name |
§remote? | string | Remote name (for remote type) |
Returns
stringFull reference name
Example
Build full reference names from type and name
buildRefName('branch', 'main') // 'refs/heads/main'
buildRefName('tag', 'v1.0.0') // 'refs/tags/v1.0.0'
buildRefName('remote', 'main', 'origin') // 'refs/remotes/origin/main'Builds a tag name from package name and version.
Parameters
Returns
stringFormatted tag name
Example
Build tag names with different formats
buildTagName('@scope/pkg', '1.2.3') // '@scope/pkg@1.2.3'
buildTagName('utils', '1.0.0', 'v${version}') // 'v1.0.0'
buildTagName('pkg', '2.0.0', '${package}-v${version}') // 'pkg-v2.0.0'Compares two references by name (alphabetically).
Returns
numberComparison result (-1, 0, or 1)
Example
Sort references alphabetically by name
const refs = [refB, refA, refC]
refs.sort(compareRefsByName) // => [refA, refB, refC]Compares two tags by version (newest first). Useful for sorting tags.
Returns
numberComparison result (-1, 0, or 1)
Example
Sort tags by version (newest first)
const tags = [tagV1, tagV2, tagV3]
tags.sort(compareTagsByVersion) // => [tagV3, tagV2, tagV1]Creates an annotated git tag.
Parameters
| Name | Type | Description |
|---|---|---|
§options | CreateAnnotatedTagOptions | Tag creation options |
Returns
GitTagA new GitTag object
Example
Create an annotated git tag with metadata
const tag = createAnnotatedTag({
name: 'v1.0.0',
commitHash: 'abc123...',
message: 'Release v1.0.0',
taggerName: 'John Doe',
taggerEmail: 'john@example.com',
tagDate: '2026-03-12T10:00:00Z',
})Creates a git commit model.
Parameters
| Name | Type | Description |
|---|---|---|
§options | CreateGitCommitOptions | Commit creation options |
Returns
GitCommitA new GitCommit object
Example
Create a git commit model
const commit = createGitCommit({
hash: 'abc123...',
authorName: 'John Doe',
authorEmail: 'john@example.com',
authorDate: '2026-03-12T10:00:00Z',
subject: 'feat: add new feature',
})Creates a git reference from full name. Parses the reference type from the full name.
Parameters
| Name | Type | Description |
|---|---|---|
§options | CreateGitRefOptions | Reference creation options |
Returns
GitRefA new GitRef object
Example
Create a git reference from full name
const ref = createGitRef({
fullName: 'refs/heads/main',
commitHash: 'abc123...',
})Creates a lightweight git tag.
Parameters
| Name | Type | Description |
|---|---|---|
§options | CreateLightweightTagOptions | Tag creation options |
Returns
GitTagA new GitTag object
Example
Create a lightweight git tag
const tag = createLightweightTag({
name: 'v1.0.0',
commitHash: 'abc123...',
})Extracts package name from tag name. Handles formats like:
@scope/package@1.2.3, package@1.2.3, package-v1.2.3 Uses character-by-character parsing (no regex).Parameters
| Name | Type | Description |
|---|---|---|
§tagName | string | Tag name to parse |
Returns
stringThe extracted package name or undefined if not found
Example
Extract package name from tag
extractPackageFromTag('@scope/pkg@1.2.3') // '@scope/pkg'
extractPackageFromTag('lib-utils@1.2.3') // 'lib-utils'
extractPackageFromTag('v1.2.3') // undefinedExtracts the scope from a commit subject if it follows conventional commit format. Uses character-by-character parsing (no regex).
Parameters
| Name | Type | Description |
|---|---|---|
§subject | string | Commit subject line |
Returns
stringScope string or undefined if no scope found
Example
Extract scope from conventional commit
extractScope('feat(lib-versioning): add git support') // 'lib-versioning'
extractScope('fix: resolve issue') // undefinedExtracts the type from a commit subject if it follows conventional commit format. Uses character-by-character parsing (no regex).
Parameters
| Name | Type | Description |
|---|---|---|
§subject | string | Commit subject line |
Returns
stringType string or undefined if no valid type found
Example
Extract type from conventional commit
extractType('feat(lib-versioning): add git support') // 'feat'
extractType('fix: resolve issue') // 'fix'
extractType('random message') // undefinedExtracts version from tag name. Handles common formats: v1.2.3,
@scope/package@1.2.3, package@1.2.3 Uses character-by-character parsing (no regex).Parameters
| Name | Type | Description |
|---|---|---|
§tagName | string | Tag name to parse |
Returns
stringThe extracted version string or undefined if no version found
Example
Extract version from various tag formats
extractVersionFromTag('v1.2.3') // '1.2.3'
extractVersionFromTag('@scope/pkg@1.2.3') // '1.2.3'
extractVersionFromTag('release-1.2.3') // '1.2.3'Filters references by remote.
Returns
unknownFiltered references
Example
Filter references by remote
const originRefs = filterRefsByRemote(remoteRefs, 'origin')
const upstreamRefs = filterRefsByRemote(remoteRefs, 'upstream')Filters references by type.
Parameters
| Name | Type | Description |
|---|---|---|
§refs | unknown | References to filter |
§type | GitRefType | Type to filter by |
Returns
unknownFiltered references
Example
Filter references by type
const branches = filterRefsByType(allRefs, 'branch')
const tags = filterRefsByType(allRefs, 'tag')Gets the tracking remote for a reference.
Returns
stringRemote name or undefined
Example
Get the remote for a reference
getRemote({ type: 'remote', name: 'main', remote: 'origin' }) // => 'origin'
getRemote({ type: 'branch', name: 'main' }) // => undefinedGets a short hash (7 characters) from a full commit hash.
Parameters
| Name | Type | Description |
|---|---|---|
§hash | string | Full commit hash |
Returns
stringShort hash (7 characters)
Example
Get short hash from full commit hash
getShortHash('abc123def456789') // => 'abc123d'Checks if a tag is annotated.
Returns
booleanTrue if tag is annotated
Example
Check if a tag is annotated
const tag = createAnnotatedTag({ name: 'v1.0.0', commitHash: 'abc123', message: 'Release' })
isAnnotatedTag(tag) // => trueChecks if a reference is a branch.
Returns
booleanTrue if reference is a branch
Example
Check if reference is a branch
isBranchRef({ type: 'branch', name: 'main' }) // => trueChecks if a reference points to the current HEAD.
Returns
booleanTrue if reference is HEAD
Example
Check if reference points to HEAD
isHeadRef({ type: 'head', name: 'HEAD' }) // => true
isHeadRef({ type: 'branch', name: 'main', isHead: true }) // => trueChecks if a tag is lightweight.
Returns
booleanTrue if tag is lightweight
Example
Check if a tag is lightweight
const tag = createLightweightTag({ name: 'v1.0.0', commitHash: 'abc123' })
isLightweightTag(tag) // => trueChecks if a commit is a merge commit (has multiple parents).
Returns
booleanTrue if commit has more than one parent
Example
Check if commit is a merge commit
if (isMergeCommit(commit)) {
console.log('Commit has parents:', commit.parents)
}Checks if a reference is a remote tracking branch.
Returns
booleanTrue if reference is a remote
Example
Check if reference is a remote tracking branch
isRemoteRef({ type: 'remote', name: 'main', remote: 'origin' }) // => trueChecks if a commit is a root commit (has no parents).
Returns
booleanTrue if commit has no parents
Example
Check if commit is the initial commit
if (isRootCommit(commit)) {
console.log('This is the initial commit')
}Checks if two commits are the same based on their hash.
Returns
booleanTrue if commits have the same hash
Example
Compare two commits by hash
isSameCommit(commitA, commitB) // => true if commitA.hash === commitB.hashChecks if a reference is a tag.
Returns
booleanTrue if reference is a tag
Example
Check if reference is a tag
isTagRef({ type: 'tag', name: 'v1.0.0' }) // => true◈ Interfaces
Options for creating an annotated tag.
Properties
Options for creating a git commit model.
Properties
Options for creating a git reference.
Properties
Options for creating a lightweight tag.
A git commit with its metadata.
Properties
A git reference.
Properties
A git tag with its metadata.
Properties
◆ Types
Type of git reference.
type GitRefType = "branch" | "tag" | "remote" | "head" | "stash"Represents either a lightweight or annotated git tag.
type GitTagType = "lightweight" | "annotated"