​

Option Types

​

AddOptions

interface AddOptions {
  flags?: (
    | "--dry-run"
    | "--force"
    | "--sparse"
    | "--update"
    | "--all"
    | "--ignore-removal"
    | "--intent-to-add"
    | "--refresh"
    | "--ignore-errors"
    | "--ignore-missing"
    | "--renormalize"
    | "--chmod=+x"
    | "--chmod=-x"
  )[]
}

​

Fields

• flags - Optional array of git add flags
  • --dry-run - Don’t actually add files, just show what would be added
  • --force - Allow adding otherwise ignored files
  • --sparse - Allow updating index entries outside of the sparse-checkout cone
  • --update - Update the index where it already has an entry
  • --all - Add changes from all tracked and untracked files
  • --ignore-removal - Add new and modified files, ignore removals
  • --intent-to-add - Record only that the path will be added later
  • --refresh - Refresh the stat information
  • --ignore-errors - Continue adding files even if some fail
  • --ignore-missing - Check if files exist before adding
  • --renormalize - Apply “clean” process to all tracked files
  • --chmod=+x - Override executable bit of added files (make executable)
  • --chmod=-x - Override executable bit of added files (make non-executable)

​

Example

await git.add('src/', {
  flags: ['--all', '--force']
})

​

BranchOptions

interface BranchOptions {
  flags?: (
    | "--all"
    | "--show-current"
    | "--list"
    | "--remotes"
    | "--force"
    | "--delete"
    | "-D"
    | "--move"
    | "-M"
    | "--copy"
    | "-C"
    | "--ignore-case"
    | "--omit-empty"
    | "--no-column"
    | "--quiet"
    | "--no-abbrev"
    | "--unset-upstream"
  )[]
  "--color"?: "always" | "auto" | "never"
  "--column"?: string
  "--sort"?: string
  "--abbrev"?: string
  "--set-upstream-to"?: string
}

​

Fields

• flags - Optional array of branch operation flags
  • Some flags require branch names: --delete, -D, --move, -M, --copy, -C
  • --all - List both remote-tracking and local branches
  • --show-current - Print the name of the current branch
  • --list - List branches
  • --remotes - List or delete remote-tracking branches
  • --force - Force creation, deletion, or renaming
  • --delete - Delete a branch
  • -D - Shortcut for --delete --force
  • --move - Move/rename a branch
  • -M - Shortcut for --move --force
  • --copy - Copy a branch
  • -C - Shortcut for --copy --force
  • --ignore-case - Sorting and filtering branches are case insensitive
  • --omit-empty - Do not print a newline after formatted refs
  • --no-column - Display branch listing in plain format
  • --quiet - Suppress non-error messages
  • --no-abbrev - Show full SHA-1 object name
  • --unset-upstream - Remove upstream information
• --color - Color branches to highlight current, local, and remote-tracking branches (default: "always")
• --column - Display branch listing in columns
• --sort - Sort branch output by the specified key
• --abbrev - Minimum abbreviation length for object names
• --set-upstream-to - Set upstream branch (e.g., "origin/main")

​

Example

await git.branch('feature-branch', {
  '--set-upstream-to': 'origin/main'
})

​

CloneOptions

interface CloneOptions {
  flags?: (
    | "--local"
    | "--no-hardlinks"
    | "--shared"
    | "--dissociate"
    | "--quiet"
    | "--progress"
    | "--no-checkout"
    | "--reject-shallow"
    | "--no-reject-shallow"
    | "--bare"
    | "--sparse"
    | "--also-filter-submodules"
    | "--mirror"
    | "--no-tags"
    | "--single-branch"
    | "--no-single-branch"
  )[]
  dir?: string
  "--filter"?: string
  "--origin"?: string
  "--branch"?: string
  "--revision"?: string
  "--upload-pack"?: string
  "--depth"?: number | string
}

​

Fields

• flags - Optional array of clone flags
  • --local - Clone from local repository
  • --no-hardlinks - Don’t use hard links for local clones
  • --shared - Share objects with source repository
  • --dissociate - Dissociate from shared object repository
  • --quiet - Suppress output
  • --progress - Show progress status
  • --no-checkout - Don’t checkout HEAD after clone
  • --reject-shallow - Fail if source is a shallow repository
  • --no-reject-shallow - Allow cloning from shallow repository
  • --bare - Create a bare repository
  • --sparse - Initialize sparse-checkout file
  • --also-filter-submodules - Apply filter to submodules
  • --mirror - Set up mirror of source repository
  • --no-tags - Don’t clone tags
  • --single-branch - Clone only one branch
  • --no-single-branch - Clone all branches
• dir - Target directory for the clone
• --filter - Object filtering specification
• --origin - Use specified name for remote (default: "origin")
• --branch - Branch to check out after clone
• --revision - Specific revision to clone
• --upload-pack - Path to git-upload-pack on remote
• --depth - Create a shallow clone with specified depth

​

Example

await git.clone('https://github.com/user/repo.git', {
  dir: './my-project',
  '--branch': 'main',
  '--depth': 1
})

​

CommitOptions

interface CommitOptions {
  flags?: (
    | "--amend"
    | "--no-verify"
    | "--signoff"
    | "--no-edit"
    | "--all"
    | "--patch"
    | "--allow-empty"
    | "--allow-empty-message"
    | "--quiet"
    | "--status"
    | "--no-status"
    | "--reset-author"
  )[]
  "--author"?: string
  "--date"?: string
  "--cleanup"?: "strip" | "whitespace" | "verbatim" | "scissors" | "default"
  "--untracked-files"?: "no" | "normal" | "all"
  "--template"?: string
  "--file"?: string
  "--gpg-sign"?: true | string
  "--squash"?: string
  "--reuse-message"?: string
  "--fixup"?: string
}

​

Fields

• flags - Optional array of commit flags
  • --amend - Replace the tip of the current branch
  • --no-verify - Bypass pre-commit and commit-msg hooks
  • --signoff - Add Signed-off-by line
  • --no-edit - Use selected commit message without launching editor
  • --all - Stage all modified and deleted files
  • --patch - Interactively select hunks to commit
  • --allow-empty - Allow empty commits
  • --allow-empty-message - Allow commits with empty messages
  • --quiet - Suppress commit summary message
  • --status - Include output of git-status
  • --no-status - Don’t include output of git-status
  • --reset-author - Reset author information
• --author - Override the commit author (format: "name <email>")
• --date - Override the author date (e.g., "2024-01-01", "yesterday", RFC 2822/ISO 8601)
• --cleanup - How to strip spaces and comments from commit message
• --untracked-files - Show untracked files (default: "all")
• --template - Use a commit message template file
• --file - Take commit message from file or stdin ("-")
• --gpg-sign - GPG-sign the commit (true for default key, or specify key ID)
• --squash - Squash commit reference
• --reuse-message - Reuse message from specified commit
• --fixup - Create a fixup commit

​

Example

await git.commit('feat: add new feature', {
  flags: ['--signoff'],
  '--author': 'John Doe <[email protected]>'
})

​

CreateTagOptions

interface CreateTagOptions {
  force?: boolean
}

​

Fields

• force - Whether to forcibly replace an existing tag (default: false)

​

Example

await git.createTag('v1.0.0', {
  force: true
})

​

DiffOptions

interface DiffOptions {
  flags?: (
    | "--patch"
    | "--stat"
    | "--numstat"
    | "--shortstat"
    | "--name-only"
    | "--name-status"
    | "--cached"
    | "--merge-base"
    | "--no-index"
    | "--raw"
    | "--quiet"
    | "--ignore-all-space"
    | "--ignore-space-at-eol"
    | "--ignore-cr-at-eol"
  )[]
}

​

Fields

• flags - Optional array of diff flags
  • --patch - Generate patch (default)
  • --stat - Generate a diffstat
  • --numstat - Show number of added/deleted lines in decimal
  • --shortstat - Output only the last line of —stat
  • --name-only - Show only names of changed files
  • --name-status - Show names and status of changed files
  • --cached - Compare staged changes
  • --merge-base - Use merge base for comparison
  • --no-index - Compare files outside working tree
  • --raw - Generate diff in raw format
  • --quiet - Disable all output
  • --ignore-all-space - Ignore whitespace changes
  • --ignore-space-at-eol - Ignore whitespace at line end
  • --ignore-cr-at-eol - Ignore carriage return at line end

​

Example

const diff = await git.diff('HEAD~1', 'HEAD', {
  flags: ['--stat', '--name-only']
})

​

InitOptions

interface InitOptions {
  flags?: ("--quiet" | "--bare")[]
  "--initial-branch"?: "main" | "master"
  "--template"?: string
  "--object-format"?: "sha1" | "sha256"
  "--separate-git-dir"?: string
}

​

Fields

• flags - Optional array of init flags
  • --quiet - Only print error and warning messages
  • --bare - Create a bare repository
• --initial-branch - Use branch-name for the initial branch (default: "main")
• --template - Specify the directory from which templates will be used
• --object-format - Hash algorithm (default: "sha1")
• --separate-git-dir - Separate git directory location (default: ".git")

​

Example

await git.init({
  '--initial-branch': 'main',
  '--object-format': 'sha256'
})

​

IsDirtyOptions

interface IsDirtyOptions {
  trackedOnly?: boolean
}

​

Fields

• trackedOnly - Ignore untracked files. When enabled, only tracked file changes (modified, staged, or deleted) will be considered (default: false)

​

Example

const dirty = await git.isDirty({
  trackedOnly: true
})

​

RestoreOptions

interface RestoreOptions {
  flags?: (
    | "--staged"
    | "--worktree"
    | "--patch"
    | "--quiet"
    | "--progress"
    | "--no-progress"
    | "--ours"
    | "--theirs"
    | "--merge"
    | "--ignore-unmerged"
    | "--overlay"
    | "--no-overlay"
    | "--recurse-submodules"
    | "--no-recurse-submodules"
  )[]
  "--source"?: string
  "--conflict"?: "merge" | "diff3" | "zdiff3"
  "--unified"?: number
}

​

Fields

• flags - Optional array of restore flags
  • --staged - Restore the index
  • --worktree - Restore the working tree (default)
  • --patch - Interactively select hunks
  • --quiet - Suppress feedback messages
  • --progress - Show progress status
  • --no-progress - Don’t show progress status
  • --ours - Check out our version for unmerged files
  • --theirs - Check out their version for unmerged files
  • --merge - Recreate conflicted merge in unmerged files
  • --ignore-unmerged - Ignore unmerged entries
  • --overlay - Never remove files
  • --no-overlay - Remove files when restoring
  • --recurse-submodules - Update submodules
  • --no-recurse-submodules - Don’t update submodules
• --source - Restore files from a specific source (commit, branch, tag) (e.g., "HEAD", "main", "HEAD~1")
• --conflict - Restore with a specific conflict style (default: "merge")
• --unified - Generate diffs with N lines of context (used with --patch)

​

Example

await git.restore('src/file.ts', {
  '--source': 'HEAD~1',
  flags: ['--staged']
})

​

StatusOptions

interface StatusOptions {
  flags?: (
    | "--short"
    | "--branch"
    | "--show-stash"
    | "--porcelain"
    | "--porcelain=v2"
    | "--long"
    | "--verbose"
    | "--ignored"
    | "--untracked-files=no"
    | "--untracked-files=normal"
    | "--untracked-files=all"
    | "--ignore-submodules=none"
    | "--ignore-submodules=untracked"
    | "--ignore-submodules=dirty"
    | "--ignore-submodules=all"
    | "--ahead-behind"
    | "--no-ahead-behind"
  )[]
}

​

Fields

• flags - Flags passed directly to git status
  • --short - Give output in short format
  • --branch - Show branch information
  • --show-stash - Show stash information
  • --porcelain - Give output in porcelain format
  • --porcelain=v2 - Give output in porcelain v2 format
  • --long - Give output in long format (default)
  • --verbose - Show staged diffs
  • --ignored - Show ignored files
  • --untracked-files=no - Show no untracked files
  • --untracked-files=normal - Show untracked files and directories
  • --untracked-files=all - Show individual files in untracked directories
  • --ignore-submodules=none - Consider all changes to submodules
  • --ignore-submodules=untracked - Ignore untracked files in submodules
  • --ignore-submodules=dirty - Ignore all changes to submodules
  • --ignore-submodules=all - Ignore all submodules
  • --ahead-behind - Compute ahead/behind counts
  • --no-ahead-behind - Don’t compute ahead/behind counts

​

Example

const status = await git.status({
  flags: ['--short', '--branch']
})

​

TagOptions

interface TagOptions {
  flags?: ("--list" | "--force" | "--ignore-case" | "--omit-empty")[]
  "--verify"?: string
  "--delete"?: string
  "--sort"?: string
  "--message"?: string
}

​

Fields

• flags - Optional array of tag flags
  • --list - List tags
  • --force - Replace existing tag
  • --ignore-case - Case-insensitive tag matching
  • --omit-empty - Don’t print empty tags
• --verify - Verify the cryptographic signature of the given tag
• --delete - Delete the given tag
• --sort - Sort tags by the given key (e.g., "version:refname")
• --message - Message for annotated tags

​

Example

await git.tag({
  '--message': 'Release version 1.0.0',
  '--sort': 'version:refname'
})