Skip to content
git-scenarios

Quick Start

Use a curated scenario

The fastest path — spin up a named scenario and test against it:

import { spinUpScenario, type TempGitRepo } from '@gfargo/git-scenarios'


describe('my tool against a PR-ready branch', () => {
  let repo: TempGitRepo


  beforeAll(async () => {
    repo = await spinUpScenario('feature-pr-ready')
  })


  afterAll(async () => {
    await repo.cleanup()
  })


  it('detects the feature branch', async () => {
    const status = await repo.git.status()
    expect(status.current).toBe('feat/widget-v2')
  })
})

Use the Jest adapter

Even less boilerplate:

import { describeWithScenario } from '@gfargo/git-scenarios/jest'


describeWithScenario('feature-pr-ready', (getRepo) => {
  it('detects the feature branch', async () => {
    const repo = getRepo()
    const status = await repo.git.status()
    expect(status.current).toBe('feat/widget-v2')
  })
})

Compose inline

Build any state from atoms when no curated scenario fits:

import { createTempGitRepo, chain, addCommit, switchToBranch, startMerge } from '@gfargo/git-scenarios'


const repo = await createTempGitRepo()
await chain(
  addCommit({ message: 'base', files: { 'src/app.ts': 'base\n' } }),
  switchToBranch('feat/theirs'),
  addCommit({ message: 'theirs', files: { 'src/app.ts': 'theirs\n' } }),
  switchToBranch('main'),
  addCommit({ message: 'ours', files: { 'src/app.ts': 'ours\n' } }),
  startMerge('feat/theirs'),
)(repo)
// repo is now mid-merge with src/app.ts conflicted

Extend a scenario

Start from a baseline and add more on top:

import { fromScenario, addCommit, writeFiles } from '@gfargo/git-scenarios'


const repo = await fromScenario('feature-pr-ready',
  addCommit({ message: 'one more commit', files: { 'extra.ts': 'x\n' } }),
  writeFiles({ 'dirty.ts': 'uncommitted\n' }),
)
// feature-pr-ready + extra commit + dirty file

Use the CLI

Test any tool against a known git state:

Terminal window
# Launch lazygit against a mid-merge conflict
npx git-scenarios create mid-merge-conflict --run "lazygit"


# Open VS Code against a dirty worktree
npx git-scenarios create dirty-many-files --run "code -n"


# Just get the path
npx git-scenarios create feature-pr-ready
# → /var/folders/.../coco-git-test-xR2qwz

Next steps