Repository

The Repository class is the main entry point for git operations. It is returned by initRepository, openRepository, and cloneRepository.

Import

Repository instances are created through the factory functions — you do not construct them directly.

import { initRepository, openRepository, cloneRepository } from "@catmint-fs/git";

Branching

currentBranch

Returns the name of the current branch, or null if HEAD is detached.

currentBranch(): Promise<string | null>

const branch = await repo.currentBranch();
console.log(branch); // "main"

createBranch

Create a new branch.

createBranch(name: string, options?: { startPoint?: string }): Promise<void>

await repo.createBranch("feature/auth");
await repo.createBranch("hotfix", { startPoint: "abc1234" });

deleteBranch

Delete a branch. Cannot delete the currently checked-out branch.

deleteBranch(name: string): Promise<void>

await repo.deleteBranch("feature/auth");

listBranches

List all local branches.

listBranches(): Promise<string[]>

const branches = await repo.listBranches();
// ["main", "develop", "feature/auth"]

renameBranch

Rename a branch.

renameBranch(oldName: string, newName: string): Promise<void>

await repo.renameBranch("feature/auth", "feature/authentication");

checkout

Switch to a branch or commit.

checkout(ref: string): Promise<void>

await repo.checkout("feature/auth");
await repo.checkout("abc1234"); // Detached HEAD

Staging

add

Stage a file for the next commit.

add(path: string): Promise<void>

await repo.add("src/index.ts");

unstage

Remove a file from the staging area without deleting it from the working tree.

unstage(path: string): Promise<void>

await repo.unstage("src/index.ts");

remove

Stage a file deletion. Removes the file from both the index and the working tree.

remove(path: string): Promise<void>

await repo.remove("old-file.ts");

status

Return the status of all tracked and untracked files.

status(): Promise<StatusEntry[]>

const entries = await repo.status();
for (const entry of entries) {
  console.log(entry.path, entry.indexStatus, entry.workingStatus);
}

See StatusEntry for the full type definition.

listFiles

List all files tracked in the index.

listFiles(): Promise<string[]>

const files = await repo.listFiles();

isIgnored

Check if a path matches .gitignore patterns.

isIgnored(path: string): Promise<boolean>

const ignored = await repo.isIgnored("node_modules/pkg/index.js");

Commits

commit

Create a new commit from the current index.

commit(options: CommitOptions): Promise<string>

Returns the OID of the new commit.

const oid = await repo.commit({
  message: "Initial commit",
  author: { name: "Alice", email: "alice@example.com" },
});

log

Retrieve the commit history.

log(options?: LogOptions): Promise<CommitInfo[]>

const commits = await repo.log();
const recent = await repo.log({ maxCount: 10 });
const fileHistory = await repo.log({ path: "src/index.ts" });

readCommit

Read a specific commit object by its OID.

readCommit(oid: string): Promise<CommitInfo>

const commit = await repo.readCommit("abc1234");
console.log(commit.message, commit.tree, commit.parents);

Merging

merge

Merge a branch into the current branch.

merge(branch: string): Promise<MergeResult>

Returns a MergeResult describing the outcome.

const result = await repo.merge("feature/login");
if (result.type === "conflict") {
  console.log("Conflicts:", result.conflicts);
}

abortMerge

Abort a conflicted merge, restoring the pre-merge state.

abortMerge(): Promise<void>

await repo.abortMerge();

Tags

createTag

Create a tag. Supports both lightweight and annotated tags.

createTag(name: string, options?: CreateTagOptions): Promise<void>

await repo.createTag("v1.0.0");
await repo.createTag("v1.0.0", {
  message: "Release 1.0.0",
  tagger: { name: "Alice", email: "alice@example.com" },
});

deleteTag

Delete a tag.

deleteTag(name: string): Promise<void>

await repo.deleteTag("v1.0.0");

listTags

List all tags.

listTags(): Promise<string[]>

const tags = await repo.listTags();

Diff

diff

Compute file and hunk-level diffs.

diff(options?: DiffOptions): Promise<DiffEntry[]>

// Working tree vs index
const diffs = await repo.diff();

// Staged changes (index vs HEAD)
const staged = await repo.diff({ staged: true });

See DiffEntry for the full type definition.

Stash

stash

Save uncommitted changes to the stash stack.

stash(options: StashOptions): Promise<void>

await repo.stash({
  message: "WIP: dashboard",
  author: { name: "Alice", email: "alice@example.com" },
});

listStashes

List all stash entries.

listStashes(): Promise<StashEntry[]>

const stashes = await repo.listStashes();

applyStash

Apply a stash without removing it from the stack.

applyStash(index: number): Promise<void>

await repo.applyStash(0);

popStash

Apply a stash and remove it from the stack.

popStash(index: number): Promise<void>

await repo.popStash(0);

dropStash

Remove a stash entry without applying it.

dropStash(index: number): Promise<void>

await repo.dropStash(0);

Reset

reset

Reset the current branch to a specific commit.

reset(target: string, options?: ResetOptions): Promise<void>

await repo.reset("HEAD~1", { mode: "soft" });
await repo.reset("abc1234", { mode: "hard" });

Remotes

addRemote

Add a remote.

addRemote(name: string, url: string): Promise<void>

await repo.addRemote("origin", "https://github.com/user/repo.git");

listRemotes

List all configured remotes.

listRemotes(): Promise<RemoteInfo[]>

const remotes = await repo.listRemotes();
// [{ name: "origin", url: "https://github.com/user/repo.git" }]

deleteRemote

Remove a remote.

deleteRemote(name: string): Promise<void>

await repo.deleteRemote("origin");

setUpstream

Set the upstream (tracking) branch for a local branch.

setUpstream(branch: string, upstream: string): Promise<void>

await repo.setUpstream("main", "origin/main");

fetch

Download objects and refs from a remote.

fetch(remote: string, options?: FetchOptions): Promise<void>

import { httpTransport } from "@catmint-fs/git";
await repo.fetch("origin", { transport: httpTransport() });

push

Upload local commits to a remote.

push(remote: string, options?: PushOptions): Promise<void>

await repo.push("origin", { transport: httpTransport() });

pull

Fetch and merge from a remote.

pull(remote: string, options?: PullOptions): Promise<void>

await repo.pull("origin", { branch: "main", transport: httpTransport() });

Config

getConfig

Read a configuration value.

getConfig(key: string): Promise<string | undefined>

const name = await repo.getConfig("user.name");

setConfig

Write a configuration value.

setConfig(key: string, value: string): Promise<void>

await repo.setConfig("user.name", "Alice");

deleteConfig

Remove a configuration value.

deleteConfig(key: string): Promise<void>

await repo.deleteConfig("user.email");

Refs

resolveRef

Resolve a ref (branch name, tag, symbolic ref) to a commit OID.

resolveRef(ref: string): Promise<string>

const oid = await repo.resolveRef("refs/heads/main");
const tagOid = await repo.resolveRef("refs/tags/v1.0.0");
const headOid = await repo.resolveRef("HEAD");

listRefs

List all refs in the repository.

listRefs(): Promise<RefEntry[]>

const refs = await repo.listRefs();
for (const ref of refs) {
  console.log(ref.name, ref.oid);
}

See Also

• initRepository
• openRepository
• cloneRepository
• httpTransport
• Types Reference