Branches & commits

Branches

functionlistBranches

listBranches(repo: Repo): Promise<Branch[]>

Returns: Promise<Branch[]>

Every branch with its tip commit — { name, commit, isDefault }[]. [] for an empty repository, not an error.

functioncreateBranchFrom

createBranchFrom(repo: Repo, name: string, startPoint?: string): Promise<void>

Parameter	Type	Description
name	string	The new branch name.
startPoint?	string	Defaults to "main".

Creates name pointing at the tip of startPoint. No checkout — this package targets bare repositories.

functiondeleteBranchByName

deleteBranchByName(repo: Repo, name: string): Promise<void>

Parameter	Type	Description
name	string	The branch to delete.

Validated internally — git.deleteBranch has no built-in ref-format check the way git.branch does, so this validates name before it ever reaches isomorphic-git.

functionassertBranchExists

assertBranchExists(repo: Repo, name: string): Promise<void>

Parameter	Type	Description
name	string	The branch to check.

Throws (isomorphic-git’s NotFoundError) unless the branch resolves. Useful as a cheap existence guard before a more expensive operation.

Danger

Every function above validates its branch-name argument with the same guard git.branch/git.writeRef use internally — git.deleteBranch and raw resolveRef/writeRef calls don’t validate ref names themselves. This is handled for you; you don’t need to pre-validate before calling these.

Commits

authorNow builds a CommitAuthor stamped with the current time — the shape every commit-writing function below expects:

interface CommitAuthor {
  name: string;
  email: string;
  timestamp: number;
  timezoneOffset: number;
}

const author = authorNow('Ada', 'ada@example.com');

functioncommitFilesToBare

commitFilesToBare(repo: Repo, options: { branch, message, author, files }): Promise<string>

Parameter	Type	Description
branch	string	The branch to commit onto (created if it doesn't exist).
message	string	Commit message.
author	CommitAuthor	From authorNow or your own.
files	Array<{ path, content }>	content is string | Uint8Array.

Returns: Promise<string>

Writes a commit directly to the bare repo — no worktree, no checkout. Each blob is content-addressed and independent of the others, so all files in the batch are written in parallel.

functiondeleteFileFromBare

deleteFileFromBare(repo: Repo, options: { branch, filePath, message, author }): Promise<string>

Parameter	Type	Description
branch	string	The branch to commit onto.
filePath	string	The path to remove.
message	string	Commit message.
author	CommitAuthor

Returns: Promise<string>

Commits the removal of one file. Throws if the branch is empty (nothing to remove).

functionwriteCommitToBare

writeCommitToBare(repo: Repo, options: { branch, message, author, buildTree }): Promise<string>

Parameter	Type	Description
branch	string	The branch to commit onto.
message	string	Commit message.
author	CommitAuthor
buildTree	(parentTreeOid?: string) => Promise<string>	Receives the parent tree oid (undefined for an empty repo), returns the new root tree oid.

Returns: Promise<string>

The primitive commitFilesToBare/deleteFileFromBare are built on — reach for it directly when neither fits (a multi-step tree rewrite, a merge commit with a synthetic tree). Handles the parent-resolution, commit-object, and ref-update mechanics; you own tree construction via buildTree.

Tip

writeCommitToBare resolves the branch’s current tip to determine the parent tree. A missing branch (an empty repo, an unborn branch) isn’t treated as an error — buildTree is called with undefined, meaning “start from an empty tree.” Any other failure (a storage error, a corrupted object) propagates instead of being silently treated as “empty repo” — this distinction matters and is worth relying on if you’re handling errors from these functions yourself.

Serialize concurrent writers to the same repo externally (a per-repo lock) — the resolve-parent → write-commit → update-ref sequence is not atomic on object storage.