git/

Add staged changes to last commit without changing message
stage(['extra-file.ts'])
amendCommitNoEdit() // adds staged files to last commit

Check if commit is reachable from HEAD
if (commitReachableFromHead(baseCommit)) {
  // Safe to use for commit range queries
  const commits = getCommitsSince(baseCommit)
} else {
  // Commit not in current history, need fallback strategy
}

// Reset working directory to match HEAD
if (discardAllChanges()) {
  console.log('Working tree reset to HEAD')
}

Discard changes in tracked files
// Discard all changes
discardChanges()

// Discard specific files
discardChanges({ files: ['package.json', 'CHANGELOG.md'] })

Typical rollback pattern
// Typical rollback pattern
if (hasUnstagedChanges()) {
  discardChanges()
}
if (hasStagedChanges()) {
  unstage(['.'])
}

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

Amend the last commit with a new message
const commit = amendCommit('feat: improved feature')

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'

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'

Create a new commit
const commit = createCommit('feat: add new feature')
const commit = createCommit('fix: resolve bug', { body: 'Detailed description' })

if (commitExists('abc123def')) {
  console.log('Commit found in repository')
}

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

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

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

Create an empty commit for CI triggers
const commit = createEmptyCommit('chore: trigger CI')

Create a git client for a repository
const git = createGitClient({ cwd: '/path/to/repo' })
const status = git.getStatus()
const commits = git.getCommitsSince('v1.0.0')

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

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

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

Create lightweight and annotated tags
// Create lightweight tag
const tag = createTag('v1.0.0')

// Create annotated tag
const tag = createTag('v1.0.0', { message: 'Release v1.0.0' })

Delete a tag by name
const deleted = deleteTag('v1.0.0')

const safeAuthor = escapeAuthor('John Doe <john@example.com>')
// => 'John Doe <john@example.com>'

const safePath = escapeFilePath('src/utils/helper.ts')
// => 'src/utils/helper.ts'
escapeFilePath('file$name.ts') // throws - '$' is invalid

escapeGitArg('John Doe <john@example.com>') // => 'John Doe <john@example.com>'

const safeMessage = escapeGitMessage('Release v1.0.0 "stable"')
// => 'Release v1.0.0 \"stable\"'

escapeGitPath('src/utils/helper.ts') // => 'src/utils/helper.ts'
escapeGitPath('path with spaces/file.ts') // => 'path with spaces/file.ts'

escapeGitRef('refs/heads/main') // => 'refs/heads/main'
escapeGitRef('feature/test') // => 'feature/test'
escapeGitRef('ref$invalid') // throws - '$' is invalid

const safePattern = escapeGitTagPattern('@scope/package@')
// => '@scope/package@'
escapeGitTagPattern('v1.0.*') // throws - '*' is invalid

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

Extract scope from conventional commit
extractScope('feat(lib-versioning): add git support') // 'lib-versioning'
extractScope('fix: resolve issue') // undefined

Extract type from conventional commit
extractType('feat(lib-versioning): add git support') // 'feat'
extractType('fix: resolve issue') // 'fix'
extractType('random message') // undefined

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'

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

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

const ahead = getAheadCount()
console.log(`${ahead} commits to push`)

const behind = getBehindCount()
console.log(`${behind} commits to pull`)

Get changed files between refs
// Files changed since diverging from main
const files = getChangedFilesBetween('origin/main')

// Files changed between two tags
const files = getChangedFilesBetween('v1.0.0', 'v2.0.0')

Get file changes with status information
const changes = getChangedFilesBetweenWithStatus('v1.0.0', 'v2.0.0')
const added = changes.filter(c => c.status === 'added')

Get a single commit by hash
const commit = getCommit('abc1234')

Get commit log with options
const commits = getCommitLog({ maxCount: 10 })
const recentChanges = getCommitLog({ from: 'v1.0.0', to: 'HEAD' })

Get commits between two references
const commits = getCommitsBetween('v1.0.0', 'v1.1.0')

Get commits since a tag
const commits = getCommitsSince('v1.0.0')

Get commit with its changed files
const commit = getCommitWithFiles('abc123')
if (commit) {
  console.log(`${commit.subject} touched ${commit.files.length} files`)
}

Get the current branch name
const branch = getCurrentBranch()

Get the current HEAD commit
const head = getHead()

const hash = getHeadHash()
// => 'abc123def456789012345678901234567890abcd'

const shortHash = getHeadShortHash()
// => 'abc123d'

Get the latest tag by creation date
const latest = getLatestTag()
const latestVersion = getLatestTag({ pattern: 'v' })

const modified = getModifiedFiles()
// => ['src/utils.ts', 'README.md']

Detect if git is mid-operation
const state = getOperationState()
if (state.inProgress) {
  console.warn(`Cannot proceed: git ${state.reason} in progress`)
}

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

Get the repository root directory
const root = getRepositoryRoot()

const staged = getStagedFiles()
// => ['src/index.ts', 'package.json']

Get the full repository status
const status = getStatus()
if (!status.clean) {
  console.log('Working tree has changes')
}

Get detailed information about a specific tag
const tag = getTag('v1.0.0')

Get all tags from the repository
const tags = getTags()
const versionTags = getTags({ pattern: 'v' })

Get tags matching a package name
const tags = getTagsForPackage('@scope/pkg')

const untracked = getUntrackedFiles()
// => ['new-file.ts', 'temp.log']

if (hasConflicts()) {
  console.log('Resolve merge conflicts before continuing')
}

Check for staged changes before committing
if (hasStagedChanges()) { createCommit('...') }

Check for unstaged changes before staging
if (hasUnstagedChanges()) { stage(['.']) }

if (hasUntrackedFiles()) {
  console.log('New files detected that are not tracked by git')
}

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

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

Check if working tree is clean
if (!isClean()) {
  throw new Error('Working tree has changes')
}

Check if directory is a git repository
if (!isGitRepository()) {
  throw new Error('Not a git repository')
}

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

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

if (isMergeCommit(commit)) {
  console.log('Commit has parents:', commit.parents)
}

Check for incomplete operations
if (isOperationInProgress()) {
  throw new Error('Complete or abort the current git operation first')
}

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

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

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

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

if (needsPull()) {
  console.log('Remote commits need to be pulled')
}

if (needsPush()) {
  console.log('Local commits need to be pushed')
}

Push a tag to remote
pushTag('v1.0.0')
pushTag('v1.0.0', 'upstream')

Stage files for commit
stage(['package.json', 'CHANGELOG.md'])
stage(['.'], { all: true })

Stage all tracked and untracked changes
stageAll() // stages all tracked and untracked changes

Check if a tag exists
if (tagExists('v1.0.0')) { ... }

Unstage files from the index
unstage(['package.json'])