@hyperfrontend/versioning/git/models

models

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

§function

buildRefName(type: GitRefType, name: string, remote?: string): string

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

string

Full 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'

§function

buildTagName(packageName: string, version: string, format: string): string

Builds a tag name from package name and version.

Parameters

Name	Type	Description
§packageName	`string`	Package name (e.g., '@scope/package' or 'package')
§version	`string`	Version string (e.g., '1.2.3')
§format	`string`	Tag format template, uses ${package} and ${version} placeholders (default: `'${package}@${version}'`)

Returns

string

Formatted 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'

§function

compareRefsByName(a: GitRef, b: GitRef): number

Compares two references by name (alphabetically).

Parameters

Name	Type	Description
§a	`GitRef`	First reference
§b	`GitRef`	Second reference

Returns

number

Comparison result (-1, 0, or 1)

Example

Sort references alphabetically by name

const refs = [refB, refA, refC]
refs.sort(compareRefsByName) // => [refA, refB, refC]

§function

compareTagsByVersion(a: GitTag, b: GitTag): number

Compares two tags by version (newest first). Useful for sorting tags.

Parameters

Name	Type	Description
§a	`GitTag`	First tag
§b	`GitTag`	Second tag

Returns

number

Comparison result (-1, 0, or 1)

Example

Sort tags by version (newest first)

const tags = [tagV1, tagV2, tagV3]
tags.sort(compareTagsByVersion) // => [tagV3, tagV2, tagV1]

§function

createAnnotatedTag(options: CreateAnnotatedTagOptions): GitTag

Creates an annotated git tag.

Parameters

Name	Type	Description
§options	`CreateAnnotatedTagOptions`	Tag creation options

Returns

GitTag

A 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',
})

§function

createGitCommitModel(options: CreateGitCommitOptions): GitCommit

Creates a git commit model.

Parameters

Name	Type	Description
§options	`CreateGitCommitOptions`	Commit creation options

Returns

GitCommit

A 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',
})

§function

createGitRef(options: CreateGitRefOptions): GitRef

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

GitRef

A new GitRef object

Example

Create a git reference from full name
const ref = createGitRef({
  fullName: 'refs/heads/main',
  commitHash: 'abc123...',
})

§function

createLightweightTag(options: CreateLightweightTagOptions): GitTag

Creates a lightweight git tag.

Parameters

Name	Type	Description
§options	`CreateLightweightTagOptions`	Tag creation options

Returns

GitTag

A new GitTag object

Example

Create a lightweight git tag
const tag = createLightweightTag({
  name: 'v1.0.0',
  commitHash: 'abc123...',
})

§function

extractPackageFromTag(tagName: string): string

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

string

The 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') // undefined

§function

extractScope(subject: string): string

Extracts 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

string

Scope 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') // undefined

§function

extractType(subject: string): string

Extracts 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

string

Type 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') // undefined

§function

extractVersionFromTag(tagName: string): string

Extracts 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

string

The 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'

§function

filterRefsByRemote(refs: unknown, remote: string): unknown

Filters references by remote.

Parameters

Name	Type	Description
§refs	`unknown`	References to filter
§remote	`string`	Remote name to filter by

Returns

unknown

Filtered references

Example

Filter references by remote

const originRefs = filterRefsByRemote(remoteRefs, 'origin')
const upstreamRefs = filterRefsByRemote(remoteRefs, 'upstream')

§function

filterRefsByType(refs: unknown, type: GitRefType): unknown

Filters references by type.

Parameters

Name	Type	Description
§refs	`unknown`	References to filter
§type	`GitRefType`	Type to filter by

Returns

unknown

Filtered references

Example

Filter references by type

const branches = filterRefsByType(allRefs, 'branch')
const tags = filterRefsByType(allRefs, 'tag')

§function

getRemote(ref: GitRef): string

Gets the tracking remote for a reference.

Parameters

Name	Type	Description
§ref	`GitRef`	Reference to check

Returns

string

Remote name or undefined

Example

Get the remote for a reference

getRemote({ type: 'remote', name: 'main', remote: 'origin' }) // => 'origin'
getRemote({ type: 'branch', name: 'main' }) // => undefined

§function

getShortHash(hash: string): string

Gets a short hash (7 characters) from a full commit hash.

Parameters

Name	Type	Description
§hash	`string`	Full commit hash

Returns

string

Short hash (7 characters)

Example

Get short hash from full commit hash

getShortHash('abc123def456789') // => 'abc123d'

§function

isAnnotatedTag(tag: GitTag): boolean

Checks if a tag is annotated.

Parameters

Name	Type	Description
§tag	`GitTag`	Tag to check

Returns

boolean

True if tag is annotated

Example

Check if a tag is annotated

const tag = createAnnotatedTag({ name: 'v1.0.0', commitHash: 'abc123', message: 'Release' })
isAnnotatedTag(tag) // => true

§function

isBranchRef(ref: GitRef): boolean

Checks if a reference is a branch.

Parameters

Name	Type	Description
§ref	`GitRef`	Reference to check

Returns

boolean

True if reference is a branch

Example

Check if reference is a branch

isBranchRef({ type: 'branch', name: 'main' }) // => true

§function

isHeadRef(ref: GitRef): boolean

Checks if a reference points to the current HEAD.

Parameters

Name	Type	Description
§ref	`GitRef`	Reference to check

Returns

boolean

True if reference is HEAD

Example

Check if reference points to HEAD

isHeadRef({ type: 'head', name: 'HEAD' }) // => true
isHeadRef({ type: 'branch', name: 'main', isHead: true }) // => true

§function

isLightweightTag(tag: GitTag): boolean

Checks if a tag is lightweight.

Parameters

Name	Type	Description
§tag	`GitTag`	Tag to check

Returns

boolean

True if tag is lightweight

Example

Check if a tag is lightweight

const tag = createLightweightTag({ name: 'v1.0.0', commitHash: 'abc123' })
isLightweightTag(tag) // => true

§function

isMergeCommit(commit: GitCommit): boolean

Checks if a commit is a merge commit (has multiple parents).

Parameters

Name	Type	Description
§commit	`GitCommit`	Commit to check

Returns

boolean

True 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)
}

§function

isRemoteRef(ref: GitRef): boolean

Checks if a reference is a remote tracking branch.

Parameters

Name	Type	Description
§ref	`GitRef`	Reference to check

Returns

boolean

True if reference is a remote

Example

Check if reference is a remote tracking branch

isRemoteRef({ type: 'remote', name: 'main', remote: 'origin' }) // => true

§function

isRootCommit(commit: GitCommit): boolean

Checks if a commit is a root commit (has no parents).

Parameters

Name	Type	Description
§commit	`GitCommit`	Commit to check

Returns

boolean

True if commit has no parents

Example

Check if commit is the initial commit

if (isRootCommit(commit)) {
  console.log('This is the initial commit')
}

§function

isSameCommit(a: GitCommit, b: GitCommit): boolean

Checks if two commits are the same based on their hash.

Parameters

Name	Type	Description
§a	`GitCommit`	First commit
§b	`GitCommit`	Second commit

Returns

boolean

True if commits have the same hash

Example

Compare two commits by hash

isSameCommit(commitA, commitB) // => true if commitA.hash === commitB.hash

§function

isTagRef(ref: GitRef): boolean

Checks if a reference is a tag.

Parameters

Name	Type	Description
§ref	`GitRef`	Reference to check

Returns

boolean

True if reference is a tag

Example

Check if reference is a tag

isTagRef({ type: 'tag', name: 'v1.0.0' }) // => true

◈ Interfaces

§interface

CreateAnnotatedTagOptions

Options for creating an annotated tag.

Properties

§readonly commitHash:string—

Target commit hash

§readonly message:string—

Tag message

§readonly name:string—

Tag name

§readonly tagDate:string—

Tag date (ISO 8601 format)

§readonly taggerEmail:string—

Tagger email

§readonly taggerName:string—

Tagger name

§interface

CreateGitCommitOptions

Options for creating a git commit model.

Properties

§readonly authorDate:string—

Author date (ISO 8601 format)

§readonly authorEmail:string—

Commit author email

§readonly authorName:string—

Commit author name

§readonly body?:string—

Full commit body (defaults to empty string)

§readonly commitDate?:string—

Commit date (defaults to author date)

§readonly committerEmail?:string—

Committer email (defaults to author)

§readonly committerName?:string—

Committer name (defaults to author)

§readonly hash:string—

Full commit hash

§readonly parents?:unknown—

Parent commit hashes (defaults to empty array)

§readonly refs?:unknown—

Associated refs (defaults to empty array)

§readonly subject:string—

Commit subject (first line of message)

§interface

CreateGitRefOptions

Options for creating a git reference.

Properties

§readonly commitHash:string—

Target commit hash

§readonly fullName:string—

Full reference name

§readonly isHead?:boolean—

Whether this is the current HEAD

§interface

CreateLightweightTagOptions

Options for creating a lightweight tag.

Properties

§readonly commitHash:string—

Target commit hash

§readonly name:string—

Tag name

§interface

GitCommit

A git commit with its metadata.

Properties

§readonly authorDate:string—

Author date (ISO 8601 format)

§readonly authorEmail:string—

Commit author email

§readonly authorName:string—

Commit author name

§readonly body:string—

Full commit body (excludes subject)

§readonly commitDate:string—

Commit date (ISO 8601 format)

§readonly committerEmail:string—

Committer email

§readonly committerName:string—

Committer name

§readonly hash:string—

Full commit hash (40 characters)

§readonly message:string—

Full commit message (subject + body)

§readonly parents:unknown—

Parent commit hashes

§readonly refs:unknown—

Associated refs (branches, tags, etc.)

§readonly shortHash:string—

Abbreviated commit hash (typically 7 characters)

§readonly subject:string—

Commit subject (first line of message)

§interface

GitRef

A git reference.

Properties

§readonly commitHash:string—

Target commit hash

§readonly fullName:string—

Full reference name (e.g., refs/heads/main)

§readonly isHead?:boolean—

Whether this is the current HEAD

§readonly name:string—

Short reference name (e.g., main)

§readonly remote?:string—

Remote name for remote refs

§readonly type:GitRefType—

Reference type

§interface

GitTag

A git tag with its metadata.

Properties

§readonly commitHash:string—

Target commit hash

§readonly message?:string—

Tag message (for annotated tags)

§readonly name:string—

Tag name

§readonly tagDate?:string—

Tag date (ISO 8601 format, for annotated tags)

§readonly taggerEmail?:string—

Tagger email (for annotated tags)

§readonly taggerName?:string—

Tagger name (for annotated tags)

§readonly type:GitTagType—

Tag type

◆ Types

§type

GitRefType

Type of git reference.

type GitRefType = "branch" | "tag" | "remote" | "head" | "stash"

§type

GitTagType

Represents either a lightweight or annotated git tag.

type GitTagType = "lightweight" | "annotated"