Class Git

A smart, user-friendly Git utility class for Node.js CLIs.

Git provides a high-level interface for interacting with Git repositories using simple, intuitive commands. Designed for use in GitNifty, it wraps common Git operations like checking repository status, retrieving user info, detecting upstream branches, and more — all with clean automation and helpful defaults.

This class is built to make version control effortless for developers who want precision and productivity, without dealing with complex Git shell commands directly.

Example

import { Git } from "./gitnifty";

const git = new Git({ cwd: "/path/to/repo" });
const username = await git.getUserName();
const branch = await git.getCurrentBranchName();
const isClean = await git.isWorkingDirClean();

Remarks

Built for Node.js CLI tools like GitNifty.
Uses child_process.exec under the hood.
Handles common Git tasks with automation-friendly methods.
Falls back gracefully on errors, e.g., hasUpstreamBranch() or isWorkingDirClean() return false instead of throwing.

See

GitOptions - Options for configuring the Git class.
Git Official Documentation

Constructors

constructor

new Git(options: GitOptions): Git
Creates an instance of the Git class.
Parameters
- options: GitOptions
  Configuration options for the Git instance.
Returns Git
Example
```
const git = new Git({ cwd: "/path/to/repo" });
```
- Defined in index.ts:297

Methods

add

add(path?: string | string[]): Promise<string>
Stages one or more files or directories for the next commit.

This method wraps git add to prepare specified files or directories for commit. You can provide a single path or an array of paths. By default, it stages all changes.
Parameters
- path: string | string[] = "."
  The file(s) or directory path(s) to stage. Use "." to stage all changes. If an array is provided, all listed paths will be staged.
Returns Promise<string>
A promise that resolves with the command's stdout if successful.
Throws
Throws an error with stderr if the command fails (e.g., invalid path).
Example
```
const git = new Git({ cwd: "/repo" });
await git.add("README.md"); // stages a single file
await git.add(["src/", "docs/"]); // stages multiple directories
await git.add(); // stages everything (default ".")
```
- Defined in index.ts:572

branch

branch(name?: string, flags?: BranchFlag | BranchFlag[]): Promise<string>
Creates, deletes, renames, or lists branches.
Parameters
- Optionalname: string
  Optional branch name. Required for some flags.
- flags: BranchFlag | BranchFlag[] = []
  Optional branch flags like -d, -m, --list, etc.
Returns Promise<string>
A promise that resolves with the result of the Git command.
Example
```
git.branch(); // git branch
git.branch("feature-x"); // git branch feature-x
git.branch("old-branch", ["-d"]); // git branch -d old-branch
git.branch(undefined, "--show-current"); // git branch --show-current
```
See
Git Branch Docs
- Defined in index.ts:865

checkout

checkout(target: string, flags?: CheckoutFlag | CheckoutFlag[]): Promise<Git>
Switches to the given branch or commit, optionally creating it.
Parameters
- target: string
  The branch, tag, or commit hash to checkout.
- Optionalflags: CheckoutFlag | CheckoutFlag[]
  Optional checkout flags like -b, --orphan, etc.
Returns Promise<Git>
A promise that resolves with the result of the Git command.
Example
```
git.checkout("main"); // git checkout main
git.checkout("new-branch", "-b"); // git checkout -b new-branch
```
See
Git Checkout Docs
- Defined in index.ts:834

clone

clone(url: string, dir?: string): Promise<Git>
Clones a Git repository into the current directory or specified folder.
Parameters
- url: string
  The Git repository URL to clone.
- dir: string = ""
  Optional directory to clone into.
Returns Promise<Git>
A promise that resolves to the Git instance.
Example
```
await git.clone("https://github.com/user/repo.git", "my-folder");
```
See
Git Clone Docs
- Defined in index.ts:714

commit

commit(message: string, flags?: CommitFlag | CommitFlag[]): Promise<Git>
Commits staged changes to the repository with a custom message and optional flags.

This method wraps git commit -m "<message>" with support for additional commit flags. It safely escapes double quotes in the commit message to avoid shell issues.
Parameters
- message: string
  The commit message to use. Will be wrapped in quotes and escaped.
- Optionalflags: CommitFlag | CommitFlag[]
  Optional list of commit flags to customize the commit behavior. Each flag must be a valid CommitFlag value.
Returns Promise<Git>
A promise that resolves with the command's stdout if the commit succeeds.
Throws
Throws an error if the commit fails (e.g., nothing staged, invalid flags).
Example
```
const git = new Git({ cwd: "/repo" });
await git.commit("feat: add login API");
await git.commit("fix: typo", ["--amend", "--no-edit"]);
```
See
- CommitFlag for supported commit flags
- Git Commit Docs
- Defined in index.ts:665

describe

describe(flags: DescribeFlag | DescribeFlag[], ref?: string): Promise<string>
Runs git describe to generate a human-readable identifier for a commit.

This wraps the git describe command and returns a string such as v1.2.3-2-gabcdef based on the most recent tag and commit information.
Parameters
- flags: DescribeFlag | DescribeFlag[]
  One or more optional git describe flags to customize the output. Can be a single flag or an array of flags.
- Optionalref: string
  Optional Git reference to describe (e.g., a branch, tag, or commit hash). Defaults to HEAD if not provided.
Returns Promise<string>
A promise that resolves with the git describe output.
Example
```
await git.describe("--tags");
await git.describe(["--tags", "--long"], "main");
await git.describe(["--dirty=*", "--abbrev=10"], "HEAD~2");
```
See
Git Describe Docs
- Defined in index.ts:897

getCurrentBranchName

getCurrentBranchName(): Promise<string>
Retrieves the name of the current branch.

Returns Promise<string>
A promise that resolves with the current branch name.
Throws
Throws an error if the command fails (e.g., not a Git repository).
Example
```
const git = new Git({ cwd: "/path/to/repo" });
const branch = await git.getCurrentBranchName();
console.log(branch); // "main"
```
- Defined in index.ts:521

getDefaultBranchName

getDefaultBranchName(): Promise<string>
Retrieves the default branch name of the repository (e.g., main or master).

Falls back to "main" if the default branch cannot be determined.

Returns Promise<string>
A promise that resolves with the default branch name.
Throws
Throws an error if the command fails (e.g., not a Git repository).
Example
```
const git = new Git({ cwd: "/path/to/repo" });
const defaultBranch = await git.getDefaultBranchName();
console.log(defaultBranch); // "main" or "master"
```
- Defined in index.ts:541

getLatestTag

getLatestTag(): Promise<string>
Retrieves the latest reachable Git tag (e.g., v1.2.3) without commit metadata.

This uses git describe --tags --abbrev=0 to return only the most recent tag name, ignoring additional suffixes like commit counts or hashes.

Returns Promise<string>
A promise that resolves with the latest tag as a string.
Example
```
await git.getLatestTag(); // "v1.2.3"
```
See
Git.describe
- Defined in index.ts:920

getUserEmail

getUserEmail(): Promise<string>
Retrieves the configured Git user email.

Returns Promise<string>
A promise that resolves with the user's email.
Throws
Throws an error if the command fails (e.g., Git not installed or email not configured).
Example
```
const git = new Git({ cwd: "/path/to/repo" });
const email = await git.getUserEmail();
console.log(email); // "john.doe@example.com"
```
- Defined in index.ts:411

getUserName

getUserName(): Promise<string>
Retrieves the configured Git user name.

Returns Promise<string>
A promise that resolves with the user's name.
Throws
Throws an error if the command fails (e.g., Git not installed or user not configured).
Example
```
const git = new Git({ cwd: "/path/to/repo" });
const username = await git.getUserName();
console.log(username); // "John Doe"
```
- Defined in index.ts:372

hasNoStagedChanges

hasNoStagedChanges(): Promise<boolean>
Checks if there are no staged but uncommitted changes.

Returns Promise<boolean>
A promise that resolves to true if there are no staged changes, otherwise false.
Example
```
const git = new Git({ cwd: "/repo" });
const clean = await git.hasNoStagedChanges();
console.log(clean); // true if nothing is staged for commit
```
- Defined in index.ts:464

hasNoUnstagedChanges

hasNoUnstagedChanges(): Promise<boolean>
Checks if there are no unstaged changes in the working directory.

Returns Promise<boolean>
A promise that resolves to true if there are no unstaged changes, otherwise false.
Example
```
const git = new Git({ cwd: "/repo" });
const clean = await git.hasNoUnstagedChanges();
console.log(clean); // true if working directory has no unstaged changes
```
- Defined in index.ts:448

hasUpstreamBranch

hasUpstreamBranch(): Promise<boolean>
Checks if the current branch has an upstream branch configured.

Returns Promise<boolean>
A promise that resolves to true if an upstream branch is set, false otherwise.
Example
```
const git = new Git({ cwd: "/path/to/repo" });
const hasUpstream = await git.hasUpstreamBranch();
console.log(hasUpstream); // true (if upstream is set), false (if not)
```
- Defined in index.ts:501

init

init(): Promise<Git>
Initializes a new Git repository in the working directory.

Returns Promise<Git>
A promise that resolves to the Git instance.
Example
```
await git.init();
await git.clone("https://github.com/repo.git");
```
See
Git Init Docs
- Defined in index.ts:694

isWorkingDirClean

isWorkingDirClean(): Promise<boolean>
Checks if the working directory is completely clean i.e., no staged or unstaged changes.

Returns Promise<boolean>
A promise that resolves to true if the working directory is fully clean, otherwise false.
Example
```
const git = new Git({ cwd: "/repo" });
const isClean = await git.isWorkingDirClean();
console.log(isClean); // true if no changes, false if dirty
```
See
- hasNoUnstagedChanges To check if working directory has unstaged changes.
- hasNoStagedChanges To check if working directory has staged but uncommitted changes.
- Defined in index.ts:483

merge

merge(branchName: string, flags?: MergeFlag | MergeFlag[]): Promise<string>
Merges the specified branch into the current branch.
Parameters
- branchName: string
  The name of the branch to merge.
- Optionalflags: MergeFlag | MergeFlag[]
  Optional merge flags like --no-ff, --squash, etc.
Returns Promise<string>
A promise that resolves with the result of the Git command.
Example
```
git.merge("feature-branch"); // git merge feature-branch
git.merge("hotfix", ["--squash", "--no-commit"]); // git merge --squash --no-commit hotfix
```
See
Git Merge Docs
- Defined in index.ts:809

push

push(
    remote?: string | PushFlag[],
    branch?: string,
    flags?: PushFlag | PushFlag[],
): Promise<Git>
Pushes changes to the specified remote and optionally to a specific branch.
Parameters
- remote: string | PushFlag[] = "origin"
  The remote name to push to. Defaults to "origin".
- branch: string = ""
  The branch name to push. If not provided, pushes all matching branches.
- flags: PushFlag | PushFlag[] = []
  Optional push flags to customize behavior. Can be a single flag or array.
Returns Promise<Git>
A promise that resolves with the result of the Git command.
Example
```
git.push(); // git push origin
git.push("origin", "main", "--force"); // git push --force origin main
git.push("origin", "dev", ["--tags", "--set-upstream"]); // git push --tags --set-upstream origin dev
```
See
Git Push Docs
- Defined in index.ts:737

reset

reset(hashValue: string, flag?: ResetFlag): Promise<string>
Resets the current HEAD to the specified commit hash, with an optional behavior flag.

This method wraps git reset <hash> <flag> and moves the current branch pointer to the given commit. It does not modify the working directory or the index unless additional flags (e.g., --hard, --soft) are added manually.
Parameters
- hashValue: string
  The target commit hash to reset to. This must be a valid Git commit SHA (full or abbreviated).
- Optionalflag: ResetFlag
  One or more Git reset flags. Examples: "--soft", "--hard".
Returns Promise<string>
A promise that resolves with the command's stdout if the reset succeeds.
Throws
Throws an error if the command fails (e.g., invalid hash or detached HEAD issues).
Example
```
const git = new Git({ cwd: "/repo" });
await git.reset("abc1234"); // Moves HEAD to commit abc1234
await git.reset("abc1234", "--hard"); // Hard reset to commit
```
- Defined in index.ts:601

restore

restore(target?: string | string[], flag?: RestoreFlag): Promise<string>
Restores working tree files from the index or a specified source.

This method wraps git restore to unstage files or restore their contents from the index (staged) or from a specific commit/branch.
Parameters
- target: string | string[] = "."
  One or more file paths to restore. Use "." to restore all tracked files. When using an array, all paths will be included.
- Optionalflag: RestoreFlag
  An optional Git restore flag like --staged or --source=<commit>. Use this to restore from a specific source or unstage changes.
Returns Promise<string>
A promise that resolves with the command's output on success.
Throws
Throws an error if the command fails (e.g., invalid path or ref).
Example
```
const git = new Git({ cwd: "/repo" });
await git.restore("README.md"); // Restore file from index
await git.restore(".", "--staged"); // Unstage all changes
await git.restore(["src/", "docs/"], "--source=HEAD~1"); // Restore from previous commit
```
See
git restore - Official Git Docs
- Defined in index.ts:632

setUserEmail

setUserEmail(email: string): Promise<string>
Sets the global Git user email.

This command configures the user.email value in the global Git configuration. It wraps git config --global user.email "<email>".
Parameters
- email: string
  The Git user email address to set.
Returns Promise<string>
A promise that resolves when the email has been successfully set.
Example
```
await git.setUserEmail("john.doe@example.com");
const email = await git.getUserEmail();
console.log(email); // "john.doe@example.com"
```
- Defined in index.ts:432

setUserName

setUserName(name: string): Promise<string>
Sets the global Git user name.

This command configures the user.name value in the global Git configuration. It wraps git config --global user.name "<name>".
Parameters
- name: string
  The Git user name to set. If it includes spaces, it will be quoted automatically.
Returns Promise<string>
A promise that resolves when the name has been successfully set.
Example
```
await git.setUserName("John Doe");
const name = await git.getUserName();
console.log(name); // "John Doe"
```
- Defined in index.ts:393

tag

tag(value: string, flags?: TagFlag | TagFlag[]): Promise<string>
Creates, deletes, or lists Git tags with optional flags.
Parameters
- value: string
  The tag name (or value depending on flags).
- Optionalflags: TagFlag | TagFlag[]
  Optional tag flags like --annotate, --delete, etc.
Returns Promise<string>
A promise that resolves with the result of the Git command.
Example
```
git.tag("v1.0.0"); // git tag v1.0.0
git.tag("v1.0.0", "--delete"); // git tag --delete v1.0.0
git.tag("v1.0.0", ["--annotate", "--force"]); // git tag --annotate --force v1.0.0
```
See
Git Tag Docs
- Defined in index.ts:784

Class Git

Example

Remarks

See

Index

Constructors

Methods

Constructors

constructor

Parameters

Returns Git

Example

Methods

add

Parameters

Returns Promise<string>

Throws

Example

branch

Parameters

Returns Promise<string>

Example

See

checkout

Parameters

Returns Promise<Git>

Example

See

clone

Parameters

Returns Promise<Git>

Example

See

commit

Parameters

Returns Promise<Git>

Throws

Example

See

describe

Parameters

Returns Promise<string>

Example

See

getCurrentBranchName

Returns Promise<string>

Throws

Example

getDefaultBranchName

Returns Promise<string>

Throws

Example

getLatestTag

Returns Promise<string>

Example

See

getUserEmail

Returns Promise<string>

Throws

Example

getUserName

Returns Promise<string>

Throws

Example

hasNoStagedChanges

Returns Promise<boolean>

Example

hasNoUnstagedChanges

Returns Promise<boolean>

Example

hasUpstreamBranch

Returns Promise<boolean>

Example

init

Returns Promise<Git>

Example

See

isWorkingDirClean

Returns Promise<boolean>

Example