operations

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

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

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

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
}

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

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

// 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(['.'])
}

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

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

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

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

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

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'])