Getting started

Install

npm

npm install git-edge isomorphic-git

pnpm

pnpm add git-edge isomorphic-git

yarn

yarn add git-edge isomorphic-git

Note

isomorphic-git is a peer dependency — install it yourself. git-fs-s3 is an optional peer on top of that: install it if you need an S3/R2-backed fs to pass in. git-edge itself works with any isomorphic-git-compatible fs, including plain node:fs.

Quick start

1. Build the { fs, gitdir, cache? } shape isomorphic-git itself expects — any compatible fs works, node:fs here.

   import fs from 'node:fs';
   
   const repo = { fs, gitdir: '/repo.git', cache: {} };

2. Merge one ref into another. threeWayMerge resolves both refs, takes the fast-forward shortcut when possible, and otherwise merges at the tree level — no worktree involved at any point.

   import { threeWayMerge, GitMergeConflictError } from 'git-edge';
   
   try {
     const { commitOid } = await threeWayMerge(repo, 'feature', 'main', {
       authorName: 'Ada',
       authorEmail: 'ada@example.com',
     });
     console.log('merged:', commitOid);
   } catch (err) {
     if (err instanceof GitMergeConflictError) {
       console.log('conflicts in:', err.conflictingPaths);
     } else {
       throw err;
     }
   }

With git-fs-s3

Same call, backed by object storage instead of local disk — this is the pairing git-edge was extracted alongside.

import { createGitFs, MemoryObjectStore } from 'git-fs-s3';
import { threeWayMerge, initBareRepo } from 'git-edge';

const fs = createGitFs(new MemoryObjectStore());
const repo = { fs, gitdir: '/repo.git', cache: {} };

await initBareRepo(repo);
// ... commits land on "feature" and "main" via git-fs-s3's fs ...
await threeWayMerge(repo, 'feature', 'main');

Tip

Neither package imports the other — they just agree on the same { fs, gitdir, cache? } shape. Swap in any isomorphic-git-compatible fs and threeWayMerge works unchanged.

Next steps

• Want to know why a merge will conflict before attempting one? See Analyzing a merge.
• Reading the same repo’s objects repeatedly (a commit list, a rendered diff)? See the parsed-object cache guide.
• Running many operations against the same repo in one process? See Repo cache & init for isomorphic-git’s own packfile cache.