The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
import { execFile } from 'node:child_process'
import { mkdir, mkdtemp, readFile, realpath, rm, symlink, writeFile } from 'node:fs/promises'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { promisify } from 'node:util'
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import { encryptDownFrame, encryptRpcResult } from './e2ee/applicationFrames.js'
import { placeholderBranch, sessionBranchNames, worktreeFolderName } from './agentNames.js'
import { nameBranchAfterSession } from './branchNaming.js'
import { fetchStartBase, harnessMadeWorktree, prepareGitProject, readGitProject, validGitPath } from './gitProject.js'
import { cloneRepository, parseProjectFolder, prepareProjectFolder } from './projectFolder.js'
import { engineSessionTitle, namingTitle } from './sessionTitle.js'
const exec = promisify(execFile)
// Real Git, several worktrees a test: slower than the default 5s under a full, parallel run.
describe('launch Git preparation', { timeout: 30_000 }, () => {
let root: string, repo: string
const git = async (...args: string[]) => (await exec('git', ['-C', repo, ...args])).stdout.trim()
/** The fixture builds its repos in the temp directory, outside the browsable home, so each read
* names that root — exactly as the daemon names the workspaces its agents are running in. */
const read = (path: string, options: { refresh?: boolean } = {}) =>
readGitProject(path, { ...options, knownRoots: [root] })
beforeEach(async () => {
root = await mkdtemp(join(tmpdir(), 'harness-git-test-'))
repo = join(root, 'project with spaces')
await mkdir(repo)
await git('init', '-b', 'main')
await git('config', 'user.name', 'Test')
await git('config', 'user.email', '[email protected]')
await git('config', 'commit.gpgsign', 'false')
await git('config', 'core.hooksPath', '/dev/null')
await mkdir(join(repo, 'src'))
await writeFile(join(repo, 'src', 'value'), 'main')
await git('add', '.')
await git('commit', '-m', 'initial')
await git('switch', '-c', 'feature')
await writeFile(join(repo, 'src', 'value'), 'feature')
await git('commit', '-am', 'feature')
await git('update-ref', 'refs/remotes/origin/feature', 'HEAD')
await git('symbolic-ref', 'refs/remotes/origin/HEAD', 'refs/remotes/origin/feature')
await git('switch', 'main')
})
afterEach(async () => { vi.unstubAllEnvs(); await rm(root, { recursive: true, force: true }) })
const options = () => ({ root: join(root, 'harnesses'), label: 'Codex', now: () => new Date(2026, 8, 21, 12, 0) })
const prepare = (source: 'worktree' | 'branch', branchRef = 'refs/heads/feature', path = repo, extra: Record<string, unknown> = {}) =>
prepareProjectFolder(parseProjectFolder({ projectSource: source, gitSource: path, branchRef, ...extra })!, options())
const worktrees = () => join(root, 'harnesses', 'worktrees', 'project with spaces')
const current = async (path: string) => (await exec('git', ['-C', path, 'branch', '--show-current'])).stdout.trim()
// 2026-10-30: the desktop's New Swarm makes its PM's worktree itself; the daemon trusts it for Claude Code only on this.
it('knows a worktree Harness made from the person\'s own checkout and worktrees', async () => {
const harnesses = join(root, 'harnesses')
const made = await prepareGitProject(repo, { root: harnesses, worktree: true, branchName: 'tidy-badger' })
expect(await harnessMadeWorktree(made, harnesses)).toBe(true)
const own = join(harnesses, 'worktrees', 'own')
await git('worktree', 'add', '-b', 'mine', own)
expect(await harnessMadeWorktree(own, harnesses)).toBe(false)
expect(await harnessMadeWorktree(repo, harnesses)).toBe(false)
expect(await harnessMadeWorktree(join(harnesses, 'worktrees'), harnesses)).toBe(false)
expect(await harnessMadeWorktree(join(root, 'missing'), harnesses)).toBe(false)
})
it('encrypts Git metadata requests and replies', () => {
expect(encryptDownFrame('git_project_info')).toBe(true)
expect(encryptRpcResult('git_project_info_result')).toBe(true)
})
it('never runs a program the repository names as its fsmonitor', async () => {
const marker = join(root, 'fsmonitor-ran')
const hook = join(root, 'fsmonitor.sh')
await writeFile(hook, `#!/bin/sh\ntouch '${marker}'\n`, { mode: 0o755 })
await git('config', 'core.fsmonitor', hook)
await read(repo)
await prepare('branch', 'refs/heads/feature')
await expect(readFile(marker)).rejects.toThrow()
})
it('reads local and remote branches without switching or creating anything', async () => {
expect(await read(repo)).toMatchObject({ isGit: true, branch: 'main', branches: [
{ ref: 'refs/heads/feature', name: 'feature', remote: false },
{ ref: 'refs/heads/main', name: 'main', remote: false },
{ ref: 'refs/remotes/origin/feature', name: 'origin/feature', remote: true },
] })
expect(await git('branch', '--show-current')).toBe('main')
expect(await git('worktree', 'list', '--porcelain')).not.toContain('harness/')
expect(await read(root)).toMatchObject({ isGit: false })
expect(await read('relative/path')).toEqual({ error: 'INVALID_PATH' })
})
it('runs git only inside the browsable home and the workspaces it was given', async () => {
// No known roots: the fixture's repo is in the temp directory, outside the home folder.
expect(await readGitProject(repo)).toEqual({ error: 'FORBIDDEN' })
expect(await readGitProject(repo, { knownRoots: [root] })).toMatchObject({ isGit: true })
// Named inside an allowed root, pointing outside it: the real path is what decides.
const outside = await mkdtemp(join(tmpdir(), 'harness-git-outside-'))
const allowed = await mkdtemp(join(tmpdir(), 'harness-git-allowed-'))
try {
await symlink(repo, join(allowed, 'link'))
expect(await readGitProject(join(allowed, 'link'), { knownRoots: [allowed] })).toEqual({ error: 'FORBIDDEN' })
// Gone, not refused: a deleted folder answers the way running git in it always did.
expect(await readGitProject(join(outside, 'gone'), { knownRoots: [outside] })).toEqual({ isGit: false, branches: [] })
} finally {
await rm(outside, { recursive: true, force: true })
await rm(allowed, { recursive: true, force: true })
}
})
it('discovers a newly pushed branch without fetching objects, then fetches only on Start', async () => {
const remote = join(root, 'remote.git')
const clone = join(root, 'other computer')
await git('clone', '--bare', repo, remote)
await git('clone', '--no-local', '--single-branch', '--branch', 'main', remote, clone)
const there = async (...args: string[]) => (await exec('git', ['-C', clone, ...args])).stdout.trim()
await git('remote', 'add', 'origin', remote)
await git('switch', '-c', 'feat/toolbar-onboarding')
await writeFile(join(repo, 'src', 'value'), 'new remote work')
await git('commit', '-am', 'new work')
await git('push', 'origin', 'feat/toolbar-onboarding')
await writeFile(join(clone, 'src', 'value'), 'unsaved local work')
const refs = await there('show-ref')
expect((await read(clone) as any).branches.map((b: any) => b.name)).not.toContain('origin/feat/toolbar-onboarding')
const info = await read(clone, { refresh: true })
expect(info).toMatchObject({ refreshed: true, branch: 'main', branches: expect.arrayContaining([
{ ref: 'refs/remotes/origin/feat/toolbar-onboarding', name: 'origin/feat/toolbar-onboarding', remote: true },
]) })
expect(await there('show-ref')).toBe(refs)
expect(await readFile(join(clone, 'src', 'value'), 'utf8')).toBe('unsaved local work')
const path = await prepare('worktree', 'refs/remotes/origin/feat/toolbar-onboarding', clone,
{ branchName: 'feat/toolbar-onboarding' })
expect(await readFile(join(path, 'src', 'value'), 'utf8')).toBe('new remote work')
expect(await there('branch', '--show-current')).toBe('main')
})
it('keeps saved branches from unreachable remotes and refreshes the others', async () => {
const remote = join(root, 'remote.git')
await git('clone', '--bare', repo, remote)
await git('remote', 'add', 'origin', join(root, 'missing.git'))
await git('remote', 'add', 'upstream', remote)
const info = await read(repo, { refresh: true })
expect(info).toMatchObject({ refreshed: false, branches: expect.arrayContaining([
{ ref: 'refs/remotes/origin/feature', name: 'origin/feature', remote: true },
{ ref: 'refs/remotes/upstream/main', name: 'upstream/main', remote: true },
]) })
expect(await git('branch', '--show-current')).toBe('main')
})
it('removes deleted remote choices after a successful lookup without changing saved refs', async () => {
const remote = join(root, 'remote.git')
await git('clone', '--bare', repo, remote)
await git('remote', 'add', 'origin', remote)
await exec('git', ['-C', remote, 'branch', '-D', 'feature'])
const info = await read(repo, { refresh: true }) as { branches: Array<{ name: string }> }
expect(info.branches.map(b => b.name)).toContain('feature')
expect(info.branches.map(b => b.name)).not.toContain('origin/feature')
expect(await git('show-ref', '--verify', 'refs/remotes/origin/feature')).toBeTruthy()
})
it('starts concurrent worktrees on distinct branches from the chosen ref and preserves dirty source files', async () => {
await writeFile(join(repo, 'src', 'value'), 'my uncommitted work')
const paths = await Promise.all([prepare('worktree'), prepare('worktree', 'refs/remotes/origin/feature')])
expect(new Set(paths).size).toBe(2)
const branches = []
for (const path of paths) {
expect(await readFile(join(path, 'src', 'value'), 'utf8')).toBe('feature')
const branch = (await exec('git', ['-C', path, 'branch', '--show-current'])).stdout.trim()
expect(branch).toMatch(/^[a-z]+-[a-z]+(-\d+)?$/)
branches.push(branch)
}
expect(new Set(branches).size).toBe(2)
expect(await readFile(join(repo, 'src', 'value'), 'utf8')).toBe('my uncommitted work')
expect(await git('branch', '--show-current')).toBe('main')
})
it('makes up a two-word branch no branch uses, in a folder named for it, grouped by repository', async () => {
expect(placeholderBranch([], () => 0)).toBe('amber-badger')
expect(placeholderBranch(['refs/heads/amber-badger', 'amber-badger-2'], () => 0)).toBe('amber-badger-3')
expect(worktreeFolderName('deehw/brave-otter')).toBe('brave-otter')
expect(worktreeFolderName('fix/login page')).toBe('loginpage')
// Two words when both carry the meaning.
expect(sessionBranchNames('Worktree and branches organization')).toEqual(['worktree-branches', 'worktree-branches-organization'])
expect(sessionBranchNames('Fix the harness list order')).toEqual(['harness-list', 'harness-list-order'])
expect(sessionBranchNames('Add dark mode to settings')).toEqual(['dark-mode', 'dark-mode-settings'])
expect(sessionBranchNames('Review and fix flaky tests')).toEqual(['flaky-tests'])
expect(sessionBranchNames('Portable harnesses, launch models')).toEqual(['portable-harnesses', 'portable-harnesses-launch'])
expect(sessionBranchNames('Release 0.3.1 notes')).toEqual(['release-notes'])
expect(sessionBranchNames('Café résumé')).toEqual(['cafe-resume'])
// One word when the second is generic, the two-word name kept for a clash.
expect(sessionBranchNames('✳ Fix: the login page — redirects twice?')).toEqual(['login', 'login-page', 'login-page-redirects'])
expect(sessionBranchNames('Onboarding experience')).toEqual(['onboarding', 'onboarding-experience'])
expect(sessionBranchNames('UI polish')).toEqual(['ui', 'ui-polish'])
// One word when that is all the title has.
expect(sessionBranchNames('Onboarding')).toEqual(['onboarding'])
expect(sessionBranchNames('Fix')).toEqual(['fix'])
expect(sessionBranchNames('0.3.1')).toEqual(['0-3', '0-3-1'])
expect(sessionBranchNames('a'.repeat(30) + ' ' + 'b'.repeat(30))).toEqual(['a'.repeat(24) + '-' + 'b'.repeat(24)])
// Real session titles from Claude Code, Codex and this repository's PRs (2026-09-25).
for (const [title, name] of [
['Catch up on autonomous-grid', 'autonomous-grid'],
['ok catch up on this landing page. we', 'landing'],
['Look at my Chrome. Open the file, au', 'chrome'],
['What time is it', 'time'],
['Build simple Pacman game', 'pacman-game'],
['Respond to greeting', 'greeting'],
['Define GPU Pod concept', 'gpu-pod'],
['Research roleplay app names', 'roleplay-app'],
['Device stuck issue', 'device-stuck'],
['Harness landing page redesign', 'harness-landing'],
['Review inventory protection', 'inventory-protection'],
['Remove Grid desktop app', 'grid-desktop'],
['feat(cli): add a Requesty preset to saved APIs', 'requesty-preset'],
['perf(desktop): redraw only terminal lines that changed', 'redraw-terminal'],
['fix(cli): unlink a linked dsh on remove instead of rmSync', 'unlink-linked'],
['feat(harnesses): add eight interactive experiences', 'interactive-experiences'],
['feat(login): record whether a sign-in came from the terminal', 'sign-in'],
['Study autonomous-code repo', 'autonomous-code'],
['8-bit CPU Fibonacci on iCEBreaker', '8-bit'],
['Restore split-right and split-down pane controls', 'split-right'],
['App auto-opening extra tabs', 'app-auto'],
['Explore print-in-place uses', 'print-place'],
['desktop: an on-screen banner for the same two moments', 'desktop'],
['Harness on-off switch', 'harness-switch'],
['Simplify Cmd-P with single-line results', 'cmd-p'],
['Give Harness Monitor its stacked-terminal identity', 'harness-monitor'],
['ci: CI and release workflows', 'ci-release'],
['catch up', 'catch'],
] as const) expect(sessionBranchNames(title)[0], title).toBe(name)
expect(sessionBranchNames('The and of')).toEqual([])
expect(sessionBranchNames('✳ ✳')).toEqual([])
expect(sessionBranchNames(null)).toEqual([])
const made = [await prepare('worktree'), await prepare('worktree')]
expect(new Set(made).size).toBe(2)
for (const path of made) {
const branch = await current(path)
expect(branch).toMatch(/^[a-z]+-[a-z]+(-\d+)?$/)
expect(path).toBe(join(worktrees(), worktreeFolderName(branch)))
expect(await git('config', '--get', `branch.${branch}.harness`)).toBe('placeholder')
}
})
it('creates a named branch once, and refuses names Git would not take', async () => {
const named = await prepare('worktree', 'refs/heads/feature', repo, { branchName: 'fix/login' })
expect(named).toBe(join(worktrees(), 'login'))
expect(await current(named)).toBe('fix/login')
expect(await git('config', '--get', 'branch.fix/login.harness')).toBe('created')
const made = await prepare('worktree', 'refs/heads/feature', repo, { branchName: 'quiet-owl', branchMode: 'placeholder' })
expect(await current(made)).toBe('quiet-owl')
expect(await git('config', '--get', 'branch.quiet-owl.harness')).toBe('placeholder')
const info = await read(repo) as { branches: Array<{ name: string; harness?: true }> }
expect(info.branches.filter(b => b.harness).map(b => b.name).sort()).toEqual(['fix/login', 'quiet-owl'])
await expect(prepare('worktree', 'refs/heads/feature', repo, { branchName: 'fix/login' })).rejects.toMatchObject({ code: 'BRANCH_EXISTS' })
await expect(prepare('worktree', 'refs/heads/feature', repo, { branchName: 'bad..name' })).rejects.toMatchObject({ code: 'INVALID_BRANCH' })
for (const extra of [{ branchName: '-x' }, { branchName: 'a b' }, { branchName: 'ok', branchMode: 'other' }]) {
expect(() => parseProjectFolder({ projectSource: 'worktree', gitSource: repo, ...extra })).toThrow()
}
})
// Desktop makes the name up before the start and keeps it; the person never chose it, so taken is no refusal.
it('gives a made-up worktree branch name that is already taken the next free number', async () => {
await git('branch', 'quiet-owl')
await git('branch', 'quiet-owl-2')
const made = await prepare('worktree', 'refs/heads/feature', repo, { branchName: 'quiet-owl', branchMode: 'placeholder' })
expect(await current(made)).toBe('quiet-owl-3')
expect(await git('config', '--get', 'branch.quiet-owl-3.harness')).toBe('placeholder')
})
it('makes a new branch for the folder itself, keeping its uncommitted work, and refuses one that exists', async () => {
await writeFile(join(repo, 'src', 'value'), 'in progress')
expect(await prepare('branch', 'refs/heads/login-fix', repo, { branchName: 'login-fix' })).toBe(repo)
expect(await git('branch', '--show-current')).toBe('login-fix')
expect(await readFile(join(repo, 'src', 'value'), 'utf8')).toBe('in progress')
await expect(prepare('branch', 'refs/heads/feature', repo, { branchName: 'feature' })).rejects.toMatchObject({ code: 'BRANCH_EXISTS' })
expect(() => parseProjectFolder({ projectSource: 'branch', gitSource: repo, branchRef: 'refs/heads/other', branchName: 'login-fix' })).toThrow()
})
it('names a made-up worktree branch after its session once, and never a pushed or chosen one', async () => {
const path = await prepare('worktree', 'refs/heads/feature', repo, { branchName: 'quiet-owl', branchMode: 'placeholder' })
expect(await nameBranchAfterSession(path, null)).toBeNull()
expect(await nameBranchAfterSession(path, 'Worktree and branches organization')).toBe('worktree-branches')
expect(await current(path)).toBe('worktree-branches')
expect(await git('config', '--get', 'branch.worktree-branches.harness')).toBe('created')
expect(await nameBranchAfterSession(path, 'A later name')).toBeNull()
expect(await current(path)).toBe('worktree-branches')
// Taken, with no third word to add: a number.
const second = await prepare('worktree', 'refs/heads/feature', repo, { branchName: 'calm-fox', branchMode: 'placeholder' })
expect(await nameBranchAfterSession(second, 'Fix the worktree branches')).toBe('worktree-branches-2')
// A clash takes the fuller name, then a third word, then numbers the shortest.
const named = async (title: string, placeholders: string[]) => {
const out = []
for (const branchName of placeholders) {
const at = await prepare('worktree', 'refs/heads/feature', repo, { branchName, branchMode: 'placeholder' })
out.push(await nameBranchAfterSession(at, title))
}
return out
}
expect(await named('Fix the login page', ['keen-lynx', 'tidy-heron', 'rosy-finch']))
.toEqual(['login', 'login-page', 'login-2'])
expect(await named('Harness monitor DDOS requests', ['warm-ibis', 'glad-crane', 'bold-lark']))
.toEqual(['harness-monitor', 'harness-monitor-ddos', 'harness-monitor-2'])
// A repository's own names are never taken, whatever the title says.
// This repository has no `master`: only the reserved list keeps a session from taking it.
expect(await git('branch', '--list', 'master')).toBe('')
expect(await named('Master', ['sunny-moose'])).toEqual(['master-2'])
// Case does not tell names apart: on macOS `Deploy` and `deploy` are one ref file.
await git('update-ref', 'refs/remotes/origin/Deploy', 'main')
expect(await named('Deploy', ['noble-reef'])).toEqual(['deploy-2'])
// A name a remote has is taken too.
const third = await prepare('worktree', 'refs/heads/feature', repo, { branchName: 'quiet-fox', branchMode: 'placeholder' })
await git('update-ref', 'refs/remotes/origin/onboarding', 'main')
expect(await nameBranchAfterSession(third, 'Onboarding experience')).toBe('onboarding-experience')
const chosen = await prepare('worktree', 'refs/heads/feature', repo, { branchName: 'fix/mine' })
expect(await nameBranchAfterSession(chosen, 'Anything')).toBeNull()
const pushed = await prepare('worktree', 'refs/heads/feature', repo, { branchName: 'sunny-owl', branchMode: 'placeholder' })
await git('config', 'branch.sunny-owl.remote', 'origin')
expect(await nameBranchAfterSession(pushed, 'Anything')).toBeNull()
expect(await current(pushed)).toBe('sunny-owl')
})
it('waits through Codex rename statuses before naming the worktree after its conversation', async () => {
const path = await prepare('worktree', 'refs/heads/feature', repo, { branchName: 'quiet-owl', branchMode: 'placeholder' })
const session = { engine: 'codex', sessionId: 'naming-test', codexHome: join(root, 'codex'), cwd: path }
await writeFile(join(path, 'src', 'value'), 'work in progress')
for (const status of ['Starting | quiet-owl', 'renaming... ⠹', 'renaming… ⠴']) {
const title = namingTitle(engineSessionTitle(session, status), session)
expect(await nameBranchAfterSession(path, title)).toBeNull()
expect(await current(path)).toBe('quiet-owl')
expect(await git('config', '--get', 'branch.quiet-owl.harness')).toBe('placeholder')
}
await mkdir(session.codexHome)
await writeFile(join(session.codexHome, 'session_index.jsonl'), JSON.stringify({
id: session.sessionId, thread_name: 'Discuss configurable harness agents',
}) + '\n')
const title = namingTitle(engineSessionTitle(session, 'renaming... ⠴'), session)
expect(await nameBranchAfterSession(path, title)).toBe('configurable-harness')
expect(await current(path)).toBe('configurable-harness')
expect(await git('config', '--get', 'branch.configurable-harness.harness')).toBe('created')
expect(await git('rev-parse', 'configurable-harness')).toBe(await git('rev-parse', 'feature'))
expect(await readFile(join(path, 'src', 'value'), 'utf8')).toBe('work in progress')
expect(await nameBranchAfterSession(path, 'A later conversation title')).toBeNull()
expect(await current(path)).toBe('configurable-harness')
})
it('checks out an existing branch as it is in a new worktree, once', async () => {
await git('branch', 'topic', 'main')
const path = await prepare('worktree', 'refs/heads/topic', repo, { branchName: 'topic', branchMode: 'existing' })
expect(path).toBe(join(worktrees(), 'topic'))
expect(await current(path)).toBe('topic')
expect(await readFile(join(path, 'src', 'value'), 'utf8')).toBe('main')
await expect(prepare('worktree', 'refs/heads/topic', repo, { branchName: 'topic', branchMode: 'existing' }))
.rejects.toMatchObject({ code: 'BRANCH_IN_USE' })
})
it('fetches a remote base first, reports the default, and tracks a remote branch under its own name', async () => {
const origin = join(root, 'origin.git'), upstream = join(root, 'upstream')
await exec('git', ['clone', '--quiet', '--bare', repo, origin])
await git('remote', 'add', 'origin', origin)
await git('fetch', '--quiet', 'origin')
await git('remote', 'set-head', 'origin', 'main')
expect(await read(repo)).toMatchObject({ defaultRef: 'refs/remotes/origin/main' })
await exec('git', ['clone', '--quiet', origin, upstream])
const up = (...args: string[]) => exec('git', ['-C', upstream, '-c', 'user.name=Test', '-c', '[email protected]', '-c', 'commit.gpgsign=false', '-c', 'core.hooksPath=/dev/null', ...args])
await writeFile(join(upstream, 'src', 'value'), 'pushed')
await up('commit', '-qam', 'pushed')
await up('push', '--quiet', 'origin', 'main', 'main:fix/typo')
await git('fetch', '--quiet', 'origin', 'fix/typo:refs/remotes/origin/fix/typo')
const fresh = await prepare('worktree', 'refs/remotes/origin/main', repo, { branchName: 'harness/fresh' })
expect(await readFile(join(fresh, 'src', 'value'), 'utf8')).toBe('pushed')
await expect(exec('git', ['-C', fresh, 'rev-parse', '--abbrev-ref', '@{upstream}'])).rejects.toThrow()
// A local branch starts from the newer of itself and its upstream.
await git('branch', '--set-upstream-to=origin/main', 'main')
await git('update-ref', 'refs/remotes/origin/main', 'main')
const behind = await prepare('worktree', 'refs/heads/main', repo, { branchName: 'from-behind' })
expect(await readFile(join(behind, 'src', 'value'), 'utf8')).toBe('pushed')
await writeFile(join(repo, 'src', 'value'), 'local')
await git('-c', 'user.name=Test', '-c', '[email protected]', 'commit', '-qam', 'local')
const ahead = await prepare('worktree', 'refs/heads/main', repo, { branchName: 'from-ahead' })
expect(await readFile(join(ahead, 'src', 'value'), 'utf8')).toBe('local')
const tracking = await prepare('worktree', 'refs/remotes/origin/fix/typo', repo, { branchName: 'fix/typo' })
expect((await exec('git', ['-C', tracking, 'rev-parse', '--abbrev-ref', '@{upstream}'])).stdout.trim()).toBe('origin/fix/typo')
})
describe('a Swarm start that names no branch', () => {
// A Swarm host clones a project once and reuses that checkout for every Builder, so its HEAD falls behind the
// remote. `branchBase: 'default'` is what a Swarm start without `branchRef` asks for.
let origin: string, managed: string
const identity = ['-c', 'user.name=Test', '-c', '[email protected]', '-c', 'commit.gpgsign=false', '-c', 'core.hooksPath=/dev/null']
const inClone = (...args: string[]) => exec('git', ['-C', managed, ...args]).then(out => out.stdout.trim())
/** What the worktree a Swarm start made shows of `src/value`. */
const swarmStart = async (extra: Record<string, unknown> = {}, path = managed) =>
readFile(join(await prepareProjectFolder(parseProjectFolder({ projectSource: 'worktree', gitSource: path, branchName: 'super-tab/start-1',
branchBase: 'default', ...extra })!, options()), 'src', 'value'), 'utf8')
beforeEach(async () => {
origin = join(root, 'origin.git'); managed = join(root, 'managed')
await exec('git', ['clone', '--quiet', '--bare', repo, origin])
await exec('git', ['clone', '--quiet', origin, managed])
})
/** Someone pushes to the remote's default branch after the managed clone was made. */
const pushToOrigin = async (value: string) => {
const pusher = join(root, 'pusher')
await exec('git', ['clone', '--quiet', origin, pusher])
await writeFile(join(pusher, 'src', 'value'), value)
await exec('git', ['-C', pusher, ...identity, 'commit', '-qam', value])
await exec('git', ['-C', pusher, 'push', '--quiet', 'origin', 'main'])
}
it('starts from the remote default branch, fetched first, and leaves the checkout\'s own branch where it was', async () => {
const before = await inClone('rev-parse', 'HEAD')
await pushToOrigin('pushed')
expect(await swarmStart()).toBe('pushed')
expect(await inClone('rev-parse', 'HEAD')).toBe(before)
expect(await inClone('rev-parse', 'refs/remotes/origin/main')).not.toBe(before)
})
it('starts from what the checkout has when the fetch fails', async () => {
await pushToOrigin('pushed')
await inClone('remote', 'set-url', 'origin', join(root, 'gone.git'))
expect(await swarmStart()).toBe('main')
})
it('starts from HEAD in a repository with no remote default branch', async () => {
const local = join(root, 'local-only')
await mkdir(local)
await exec('git', ['-C', local, 'init', '-q', '-b', 'trunk'])
await mkdir(join(local, 'src'))
await writeFile(join(local, 'src', 'value'), 'trunk')
await exec('git', ['-C', local, 'add', '.'])
await exec('git', ['-C', local, ...identity, 'commit', '-qm', 'initial'])
expect(await swarmStart({}, local)).toBe('trunk')
})
it('names the default branch when the remote has no origin/HEAD but has main', async () => {
await pushToOrigin('pushed')
await inClone('remote', 'set-head', 'origin', '--delete')
expect(await swarmStart()).toBe('pushed')
})
it('fetches nothing for another person\'s Swarm start: its host fetched with the app\'s token, and the worktree starts from that', async () => {
const before = await inClone('rev-parse', 'refs/remotes/origin/main')
await pushToOrigin('pushed')
// The daemon's own git setup is never asked: offline, the worktree starts from what the checkout has.
const offline = await prepareProjectFolder({ source: 'worktree', gitSource: managed, branchName: 'super-tab/start-1', fromDefaultBranch: true, offline: true }, options())
expect(await readFile(join(offline, 'src', 'value'), 'utf8')).toBe('main')
expect(await inClone('rev-parse', 'refs/remotes/origin/main')).toBe(before)
// Only the daemon sets it: a client cannot ask for it.
expect(parseProjectFolder({ projectSource: 'worktree', gitSource: managed, branchBase: 'default', offline: true })).not.toHaveProperty('offline')
// The host's fetch, with the environment it is given in place of the daemon's.
const env = { ...process.env, GIT_CONFIG_PARAMETERS: `'harness.fixture'='yes'` }
expect(await fetchStartBase(managed, env)).toBe(true)
expect(await inClone('rev-parse', 'refs/remotes/origin/main')).not.toBe(before)
const folder = await prepareProjectFolder({ source: 'worktree', gitSource: managed, branchName: 'super-tab/start-2', fromDefaultBranch: true, offline: true }, options())
expect(await readFile(join(folder, 'src', 'value'), 'utf8')).toBe('pushed')
})
it('a host\'s fetch does nothing outside a checkout or without a default branch, and says when it could not fetch', async () => {
expect(await fetchStartBase('relative/path', process.env)).toBe(false)
expect(await fetchStartBase(join(root, 'nowhere'), process.env)).toBe(false)
const local = join(root, 'no-remote')
await mkdir(local)
await exec('git', ['-C', local, 'init', '-q', '-b', 'trunk'])
await exec('git', ['-C', local, ...identity, 'commit', '-q', '--allow-empty', '-m', 'initial'])
expect(await fetchStartBase(local, process.env)).toBe(false)
await inClone('remote', 'set-url', 'origin', join(root, 'gone.git'))
expect(await fetchStartBase(managed, process.env)).toBe(false)
})
it('starts from the branch it is given, not the default one', async () => {
await pushToOrigin('pushed')
expect(await swarmStart({ branchBase: undefined, branchRef: 'refs/remotes/origin/feature' })).toBe('feature')
})
it('is not what a start from Desktop or the CLI does: without the flag the checkout\'s HEAD is used and nothing is fetched', async () => {
const before = await inClone('rev-parse', 'refs/remotes/origin/main')
await pushToOrigin('pushed')
expect(await swarmStart({ branchBase: undefined })).toBe('main')
expect(await inClone('rev-parse', 'refs/remotes/origin/main')).toBe(before)
})
it('is accepted only for a worktree that names no branch', () => {
const parse = (extra: Record<string, unknown>) => () => parseProjectFolder({ projectSource: 'worktree', gitSource: managed,
branchName: 'super-tab/start-1', ...extra })
expect(parse({ branchBase: 'default' })()).toMatchObject({ source: 'worktree', fromDefaultBranch: true })
expect(parseProjectFolder({ projectSource: 'worktree', gitSource: managed, branchBase: 'default' })).toMatchObject({ fromDefaultBranch: true })
expect(parse({})()).not.toHaveProperty('fromDefaultBranch')
expect(parse({ branchBase: 'default', branchRef: 'refs/remotes/origin/main' })).toThrow()
expect(parse({ branchBase: 'main' })).toThrow()
expect(parse({ branchBase: true })).toThrow()
expect(() => parseProjectFolder({ projectSource: 'branch', gitSource: managed, branchRef: 'refs/heads/main', branchBase: 'default' })).toThrow()
})
it('does not change a direct prepareGitProject call', async () => {
await pushToOrigin('pushed')
const path = await prepareGitProject(managed, { root: join(root, 'harnesses'), worktree: true, branchName: 'plain' })
expect(await readFile(join(path, 'src', 'value'), 'utf8')).toBe('main')
const asked = await prepareGitProject(managed, { root: join(root, 'harnesses'), worktree: true, branchName: 'asked', fromDefaultBranch: true })
expect(await readFile(join(asked, 'src', 'value'), 'utf8')).toBe('pushed')
})
})
describe('a Swarm start for another person\'s work in a blob-less, single-branch clone', () => {
// The project clone fetches only the default branch, and file contents as they are needed (projectFolder.ts). A start
// for another person's work is offline: its host fetches with the app's token first, and the owner's login is never
// used, so nothing may be fetched lazily while its worktree is made.
let origin: string, managed: string, contacts: string
const identity = ['-c', 'user.name=Test', '-c', '[email protected]', '-c', 'commit.gpgsign=false', '-c', 'core.hooksPath=/dev/null']
const inClone = (...args: string[]) => exec('git', ['-C', managed, ...args]).then(out => out.stdout.trim())
const offlineStart = (name: string, extra: Partial<{ branchRef: string }> = {}) => prepareProjectFolder({ source: 'worktree', gitSource: managed,
branchName: name, offline: true, ...(extra.branchRef ? { branchRef: extra.branchRef } : { fromDefaultBranch: true }) }, options())
/** Someone pushes [value] to [branch] after the managed clone was made. */
const pushToOrigin = async (branch: string, value: string) => {
const pusher = join(root, `pusher-${branch}`)
await exec('git', ['clone', '--quiet', '--branch', branch, origin, pusher])
await writeFile(join(pusher, 'src', 'value'), value)
await exec('git', ['-C', pusher, ...identity, 'commit', '-qam', value])
await exec('git', ['-C', pusher, 'push', '--quiet', 'origin', branch])
}
beforeEach(async () => {
origin = join(root, 'origin.git'); managed = join(root, 'managed'); contacts = join(root, 'contacts.log')
await exec('git', ['clone', '--quiet', '--bare', repo, origin])
for (const key of ['uploadpack.allowFilter', 'uploadpack.allowAnySHA1InWant']) await exec('git', ['-C', origin, 'config', key, 'true'])
await cloneRepository(`file://${origin}`, managed)
// Every time this clone asks the origin for anything, it says so.
const uploadPack = join(root, 'upload-pack')
await writeFile(uploadPack, `#!/bin/sh\necho contact >> '${contacts}'\nexec git-upload-pack "$@"\n`, { mode: 0o755 })
await inClone('config', 'remote.origin.uploadpack', uploadPack)
})
it('fetches the start\'s own base branch and its files with the token, so its offline worktree needs nothing else', async () => {
await pushToOrigin('feature', 'feature, later')
expect(await fetchStartBase(managed, process.env, 'refs/remotes/origin/feature')).toBe(true)
await rm(origin, { recursive: true })
const folder = await offlineStart('super-tab/start-1', { branchRef: 'refs/remotes/origin/feature' })
expect(await readFile(join(folder, 'src', 'value'), 'utf8')).toBe('feature, later')
})
it('fetches the default branch and its files when the start names no branch', async () => {
await pushToOrigin('main', 'main, later')
expect(await fetchStartBase(managed, process.env)).toBe(true)
await rm(origin, { recursive: true })
expect(await readFile(join(await offlineStart('super-tab/start-1'), 'src', 'value'), 'utf8')).toBe('main, later')
})
it('never fetches missing files while making an offline worktree', async () => {
await pushToOrigin('main', 'main, later')
// The branch, without its files: what a fetch with no file contents leaves.
await inClone('fetch', '--quiet', '--no-tags', 'origin', '+refs/heads/main:refs/remotes/origin/main')
await rm(contacts, { force: true })
// The start says what is wrong: the branch's files are not here, not Git or folder permissions.
await expect(offlineStart('super-tab/start-1')).rejects.toThrow("This branch's files could not be fetched for the start. Check the connection, then retry.")
expect(await readFile(contacts, 'utf8').catch(() => '')).toBe('')
})
it('says so when the files of a start\'s branch could not be fetched', async () => {
await pushToOrigin('main', 'main, later')
// The branch comes; the request for its files fails.
const flaky = join(root, 'flaky-upload-pack'), served = join(root, 'served')
await writeFile(flaky, `#!/bin/sh\n[ -e '${served}' ] && exit 1\ntouch '${served}'\nexec git-upload-pack "$@"\n`, { mode: 0o755 })
await inClone('config', 'remote.origin.uploadpack', flaky)
const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
try {
expect(await fetchStartBase(managed, process.env)).toBe(true)
expect(warn).toHaveBeenCalledWith(expect.stringContaining('could not fetch the files of refs/remotes/origin/main'))
} finally { warn.mockRestore() }
})
// GIT_NO_LAZY_FETCH is read only by git 2.44 and later (Ubuntu 22.04 ships 2.34, Debian 12 2.39): review 1 of #2770.
it('never fetches missing files offline even with a git that ignores GIT_NO_LAZY_FETCH', async () => {
await pushToOrigin('main', 'main, later')
await inClone('fetch', '--quiet', '--no-tags', 'origin', '+refs/heads/main:refs/remotes/origin/main')
await rm(contacts, { force: true })
const realGit = (await exec('sh', ['-c', 'command -v git'])).stdout.trim()
const olderGit = join(root, 'older-git')
await mkdir(olderGit)
await writeFile(join(olderGit, 'git'), `#!/bin/sh\nunset GIT_NO_LAZY_FETCH\nexec '${realGit}' "$@"\n`, { mode: 0o755 })
vi.stubEnv('PATH', `${olderGit}:${process.env.PATH}`)
await expect(offlineStart('super-tab/start-1')).rejects.toThrow()
expect(await readFile(contacts, 'utf8').catch(() => '')).toBe('')
})
})
describe('a worktree whose git is slow or fails', () => {
const harnesses = () => join(root, 'harnesses')
const listed = () => git('worktree', 'list', '--porcelain')
/** A file checked out through the `name` filter, whose smudge command is [smudge]. Set after the
* commit: `git add` needs no filter. */
const filtered = async (name: string, smudge: string) => {
await writeFile(join(repo, '.gitattributes'), `filtered filter=${name}\n`)
await writeFile(join(repo, 'filtered'), 'content\n')
await git('add', '.')
await git('commit', '-m', 'filtered file')
await git('config', `filter.${name}.smudge`, smudge)
await git('config', `filter.${name}.required`, 'true')
}
afterEach(() => { vi.restoreAllMocks() })
it('uses a checkout that finished although git was still running at the timeout, and stops what git left running', async () => {
// git checked everything out and is in its post-checkout hook when the time runs out.
const hooks = join(root, 'hooks')
await mkdir(hooks)
const pidFile = join(root, 'hook.pid')
await writeFile(join(hooks, 'post-checkout'), `#!/bin/sh\necho $$ > '${pidFile}'\nexec sleep 60\n`, { mode: 0o755 })
await git('config', 'core.hooksPath', hooks)
const path = await prepareGitProject(repo, { root: harnesses(), worktree: true, branchName: 'slow', worktreeTimeout: 1_500 })
expect(path).toBe(join(worktrees(), 'slow'))
expect(await readFile(join(path, 'src', 'value'), 'utf8')).toBe('main')
expect(await current(path)).toBe('slow')
expect(await git('config', '--get', 'branch.slow.harness')).toBe('created')
// Unlocked: git marks a worktree locked while it is being made.
const real = await realpath(path)
const entry = (await listed()).split(/\n\s*\n/).find(block => block.includes(`worktree ${real}`))
expect(entry).toBeDefined()
expect(entry).not.toContain('locked')
const hookPid = Number((await readFile(pidFile, 'utf8')).trim())
expect(() => process.kill(hookPid, 0)).toThrow()
}, 20_000)
it('removes the partial folder and its new branch when the checkout is cut off at the timeout', async () => {
await filtered('slow', 'sleep 60; cat')
await expect(prepareGitProject(repo, { root: harnesses(), worktree: true, branchName: 'cut', worktreeTimeout: 1_500 }))
.rejects.toMatchObject({ code: 'WORKTREE_FAILED' })
await expect(readFile(join(worktrees(), 'cut', 'src', 'value'))).rejects.toThrow()
await expect(realpath(join(worktrees(), 'cut'))).rejects.toThrow()
expect(await git('branch', '--list', 'cut')).toBe('')
expect(await listed()).not.toContain('cut')
}, 20_000)
it('says why git failed, without credentials, and leaves no partial folder or new branch', async () => {
const said = vi.spyOn(console, 'error').mockImplementation(() => {})
await filtered('broken', "echo 'cannot reach https://robot:[email protected]/lfs' >&2; exit 1")
await expect(prepareGitProject(repo, { root: harnesses(), worktree: true, branchName: 'broken' }))
.rejects.toMatchObject({ code: 'WORKTREE_FAILED' })
const lines = said.mock.calls.map(call => call.join(' ')).filter(line => line.startsWith('[worktree]'))
expect(lines).toHaveLength(1)
expect(lines[0]).toContain('exit 128')
expect(lines[0]).toContain('cannot reach https://')
expect(lines[0]).not.toContain('s3cret-token')
await expect(realpath(join(worktrees(), 'broken'))).rejects.toThrow()
expect(await git('branch', '--list', 'broken')).toBe('')
expect(await listed()).not.toContain('broken')
// The next start finds the name free.
await git('config', '--unset', 'filter.broken.required')
await git('config', 'filter.broken.smudge', 'cat')
expect(await prepareGitProject(repo, { root: harnesses(), worktree: true, branchName: 'broken' })).toBe(join(worktrees(), 'broken'))
})
it('leaves a registration that existed before the failed start, even one for the same folder', async () => {
vi.spyOn(console, 'error').mockImplementation(() => {})
// An earlier worktree at the folder this start picks, whose folder was deleted without `git worktree remove`.
await git('worktree', 'add', '-b', 'earlier', '--', join(worktrees(), 'again'), 'main')
await rm(join(worktrees(), 'again'), { recursive: true, force: true })
await expect(prepareGitProject(repo, { root: harnesses(), worktree: true, branchName: 'again' }))
.rejects.toMatchObject({ code: 'WORKTREE_FAILED' })
expect(await listed()).toContain('branch refs/heads/earlier')
expect(await git('branch', '--list', 'again')).toBe('')
})
it('never deletes a branch a person made at their own commit after the first check and before the add', async () => {
vi.spyOn(console, 'error').mockImplementation(() => {})
// git, as the daemon runs it, with the person's own `git branch mine feature` landing just after the name was checked.
const realGit = (await exec('sh', ['-c', 'command -v git'])).stdout.trim()
const bin = join(root, 'bin'), made = join(root, 'person-made-it')
await mkdir(bin)
await writeFile(join(bin, 'git'), `#!/bin/sh\nfor arg in "$@"; do if [ "$arg" = check-ref-format ] && [ ! -e '${made}' ]; then\n`
+ ` : > '${made}'; '${realGit}' -C '${repo}' branch mine feature\nfi; done\nexec '${realGit}' "$@"\n`, { mode: 0o755 })
vi.stubEnv('PATH', `${bin}:${process.env.PATH}`)
await expect(prepareGitProject(repo, { root: harnesses(), worktree: true, branchName: 'mine' })).rejects.toMatchObject({ code: 'BRANCH_EXISTS' })
expect(await git('rev-parse', 'mine')).toBe(await git('rev-parse', 'feature'))
await expect(realpath(join(worktrees(), 'mine'))).rejects.toThrow()
expect(await listed()).not.toContain('worktrees/project with spaces/mine')
})
it('logs none of a stateless GitHub token git printed', async () => {
const said = vi.spyOn(console, 'error').mockImplementation(() => {})
const payload = 'eyJpc3MiOiIxMjM0NTYifQ', signature = `${'s'.repeat(470)}-x_y`
await filtered('leaky', `echo 'remote refused (token "ghs_123456_eyJhbGciOiJSUzI1NiJ9.${payload}.${signature}"), retry.' >&2; exit 1`)
await expect(prepareGitProject(repo, { root: harnesses(), worktree: true, branchName: 'leaky' })).rejects.toMatchObject({ code: 'WORKTREE_FAILED' })
const line = said.mock.calls.map(call => call.join(' ')).find(text => text.startsWith('[worktree]'))!
expect(line).toContain('remote refused (token "')
expect(line).not.toContain('ghs_123456_')
expect(line).not.toContain(payload)
expect(line).not.toContain('ssssssss')
expect(line).not.toContain('-x_y')
})
describe('on Windows, where taskkill cannot stop what git started', () => {
const platform = process.platform
beforeEach(async () => {
Object.defineProperty(process, 'platform', { value: 'win32', configurable: true })
const bin = join(root, 'bin')
await mkdir(bin)
await writeFile(join(bin, 'taskkill'), '#!/bin/sh\necho \'ERROR: The process with PID 1 could not be terminated.\' >&2\nexit 1\n', { mode: 0o755 })
vi.stubEnv('PATH', `${bin}:${process.env.PATH}`)
})
afterEach(() => { Object.defineProperty(process, 'platform', { value: platform, configurable: true }) })
/** git checks out and exits; its post-checkout hook leaves a process behind, holding git's stderr, that ends after
* [seconds] by touching `ended`. */
const leftBehind = async (seconds: number) => {
const hooks = join(root, 'hooks')
await mkdir(hooks)
await writeFile(join(hooks, 'post-checkout'), `#!/bin/sh\n(sleep ${seconds}; : > '${join(root, 'ended')}') &\nexit 0\n`, { mode: 0o755 })
await git('config', 'core.hooksPath', hooks)
}
it('waits for what git left running to end before it looks at the checkout, and says taskkill failed', async () => {
const said = vi.spyOn(console, 'error').mockImplementation(() => {})
await leftBehind(2)
const path = await prepareGitProject(repo, { root: harnesses(), worktree: true, branchName: 'outlived', worktreeTimeout: 1_500 })
expect(await readFile(join(root, 'ended'), 'utf8')).toBe('')
expect(await readFile(join(path, 'src', 'value'), 'utf8')).toBe('main')
expect(said.mock.calls.map(call => call.join(' ')).join('\n')).toMatch(/\[worktree\] could not stop git.*could not be terminated/)
}, 20_000)
it('removes nothing while something git started may still be writing', async () => {
const said = vi.spyOn(console, 'error').mockImplementation(() => {})
await leftBehind(8)
await expect(prepareGitProject(repo, { root: harnesses(), worktree: true, branchName: 'still-running', worktreeTimeout: 1_500 }))
.rejects.toMatchObject({ code: 'WORKTREE_FAILED' })
await expect(readFile(join(root, 'ended'))).rejects.toThrow()
expect(await readFile(join(worktrees(), 'still-running', 'src', 'value'), 'utf8')).toBe('main')
expect(said.mock.calls.map(call => call.join(' ')).join('\n')).toMatch(/\[worktree\] .*still running.*left as it is/)
}, 20_000)
})
it('never deletes a branch that existed before the failed start', async () => {
vi.spyOn(console, 'error').mockImplementation(() => {})
await filtered('broken', 'exit 1')
await git('branch', 'topic', 'main')
const before = await git('rev-parse', 'topic')
await expect(prepareGitProject(repo, { root: harnesses(), worktree: true, branchName: 'topic', existingBranch: true }))
.rejects.toMatchObject({ code: 'WORKTREE_FAILED' })
expect(await git('rev-parse', 'topic')).toBe(before)
await expect(realpath(join(worktrees(), 'topic'))).rejects.toThrow()
expect(await listed()).not.toContain('topic')
})
})
it('copies ignored files named in .worktreeinclude into new worktrees', async () => {
await writeFile(join(repo, '.gitignore'), '.env\n*.log\nlocal/\n')
await writeFile(join(repo, '.worktreeinclude'), '.env\nlocal/\n')
await writeFile(join(repo, '.env'), 'SECRET=1')
await writeFile(join(repo, 'debug.log'), 'noise')
await mkdir(join(repo, 'local'))
await writeFile(join(repo, 'local', 'settings.json'), '{}')
const path = await prepare('worktree')
expect(await readFile(join(path, '.env'), 'utf8')).toBe('SECRET=1')
expect(await readFile(join(path, 'local', 'settings.json'), 'utf8')).toBe('{}')
await expect(readFile(join(path, 'debug.log'))).rejects.toThrow()
})
it('reads a linked worktree as its repository, and a worktree started from one joins the same repository', async () => {
const linked = await prepare('worktree', 'refs/heads/feature', repo, { branchName: 'harness/linked' })
const info = await read(join(linked, 'src'))
expect(info).toMatchObject({ isGit: true, branch: 'harness/linked', mainBranch: 'main' })
expect(await realpath((info as { mainFolder: string }).mainFolder)).toBe(await realpath(join(repo, 'src')))
const branches = (info as { branches: Array<{ name: string; worktree?: string }> }).branches
expect(await realpath(branches.find(branch => branch.name === 'harness/linked')!.worktree!)).toBe(await realpath(linked))
expect(await realpath(branches.find(branch => branch.name === 'main')!.worktree!)).toBe(await realpath(repo))
expect(await read(repo)).not.toHaveProperty('mainFolder')
expect(await prepare('worktree', 'refs/heads/main', linked, { branchName: 'harness/second' })).toBe(join(worktrees(), 'second'))
})
it('keeps the selected subfolder in its new worktree', async () => {
const path = await prepare('worktree', 'refs/heads/feature', join(repo, 'src'))
expect(await readFile(join(path, 'value'), 'utf8')).toBe('feature')
expect(path.endsWith('/src/')).toBe(false)
})
it('switches the shared folder only when requested, without forcing conflicting changes', async () => {
expect(await prepare('branch')).toBe(repo)
expect(await git('branch', '--show-current')).toBe('feature')
await writeFile(join(repo, 'src', 'value'), 'keep this')
await expect(prepare('branch', 'refs/heads/main')).rejects.toMatchObject({ code: 'BRANCH_SWITCH_FAILED' })
expect(await git('branch', '--show-current')).toBe('feature')
expect(await readFile(join(repo, 'src', 'value'), 'utf8')).toBe('keep this')
expect(await git('stash', 'list')).toBe('')
// Selecting the current branch is a no-op even with dirty files.
expect(await prepare('branch')).toBe(repo)
await git('checkout', '--', '.')
await writeFile(join(repo, 'notes.txt'), 'untracked')
await expect(prepare('branch', 'refs/heads/main')).rejects.toMatchObject({ code: 'BRANCH_SWITCH_FAILED' })
expect(await git('branch', '--show-current')).toBe('feature')
})
it('opens a branch checked out elsewhere in its worktree, and refuses missing refs, revision expressions, and untracked subfolders', async () => {
await git('worktree', 'add', join(root, 'other'), 'feature')
expect(await realpath(await prepare('branch'))).toBe(await realpath(join(root, 'other')))
expect(await realpath(await prepare('branch', 'refs/heads/feature', join(repo, 'src')))).toBe(await realpath(join(root, 'other', 'src')))
expect(await git('branch', '--show-current')).toBe('main')
for (const ref of ['refs/heads/missing', 'refs/heads/main~0', 'refs/heads/main^{commit}']) {
await expect(prepare('worktree', ref)).rejects.toMatchObject({ code: 'GIT_PROJECT_UNAVAILABLE' })
}
await mkdir(join(repo, 'untracked'))
await expect(prepare('worktree', 'refs/heads/main', join(repo, 'untracked'))).rejects.toMatchObject({ code: 'GIT_PROJECT_UNAVAILABLE' })
expect(() => parseProjectFolder({ projectSource: 'branch', gitSource: repo, branchRef: 'refs/remotes/origin/feature' })).toThrow()
})
it('detects an empty repository but refuses a worktree until its first commit', async () => {
const empty = join(root, 'empty')
await mkdir(empty)
await exec('git', ['-C', empty, 'init', '-b', 'main'])
expect(await read(empty)).toMatchObject({ isGit: true, branch: 'main', branches: [] })
await expect(prepareProjectFolder({ source: 'worktree', gitSource: empty }, options()))
.rejects.toMatchObject({ code: 'GIT_PROJECT_UNAVAILABLE' })
})
it('validates source paths and requires an exact local branch when isolation is disabled', async () => {
for (const path of [null, 7, '', 'relative', '/bad\npath', '/bad\0path', `/${'x'.repeat(4096)}`]) {
expect(validGitPath(path)).toBe(false)
expect(() => parseProjectFolder({ projectSource: 'worktree', gitSource: path })).toThrow()
}
await expect(prepareGitProject('relative', { ...options(), worktree: true }))
.rejects.toMatchObject({ code: 'INVALID_PROJECT_SOURCE' })
await expect(prepareGitProject(repo, { ...options(), worktree: true, ref: '--help' }))
.rejects.toMatchObject({ code: 'GIT_PROJECT_UNAVAILABLE' })
for (const ref of [undefined, 'refs/remotes/origin/feature']) {
await expect(prepareGitProject(repo, { ...options(), worktree: false, ref }))
.rejects.toMatchObject({ code: 'INVALID_BRANCH' })
}
for (const payload of [
{ branchRef: 7 }, { branchRef: 'refs/heads/bad name' },
{ branchRef: `refs/heads/${'x'.repeat(1024)}` }, { repositoryUrl: 'https://github.com/a/b' },
]) {
expect(() => parseProjectFolder({ projectSource: 'worktree', gitSource: repo, ...payload })).toThrow()
}
})
it('supports detached HEAD, default worktree names, and switching back to a local branch', async () => {
await git('checkout', '--detach', 'HEAD')
expect(await read(repo)).toMatchObject({ isGit: true, branch: null })
const path = await prepareGitProject(repo, { root, worktree: true })
expect(await readFile(join(path, 'src', 'value'), 'utf8')).toBe('main')
expect(path).toMatch(/\/worktrees\/project with spaces\/[a-z]+-[a-z]+(-\d+)?$/)
expect(await prepare('branch')).toBe(repo)
expect(await git('branch', '--show-current')).toBe('feature')
})
it('distinguishes an unavailable Git executable from a non-Git folder', async () => {
vi.stubEnv('PATH', join(root, 'missing-binaries'))
expect(await read(repo)).toEqual({ error: 'GIT_UNAVAILABLE' })
})
// A fresh Mac's /usr/bin/git is Apple's Command Line Tools installer stub, which exits 1. A folder
// that is not a checkout must still read as one without git, or no harness can start in it.
it('reads a non-Git folder without running git, so the macOS installer stub cannot fail it', async () => {
const stubs = join(root, 'stub-bin')
await mkdir(stubs)
await writeFile(join(stubs, 'git'), '#!/bin/sh\necho "xcode-select: note: No developer tools were found, requesting install." >&2\nexit 1\n', { mode: 0o755 })
vi.stubEnv('PATH', stubs)
const plain = join(root, 'plain project')
await mkdir(plain)
expect(await read(plain)).toEqual({ isGit: false, branches: [] })
expect(await read(repo)).toEqual({ error: 'GIT_UNAVAILABLE' })
})
it('reports unreadable refs instead of silently treating the repository as non-Git', async () => {
await writeFile(join(repo, '.git', 'packed-refs'), 'invalid packed refs\n')
expect(await read(repo)).toEqual({ error: 'GIT_UNAVAILABLE' })
})
it('rejects a subfolder that became a file on the selected branch', async () => {
await git('switch', 'feature')
await git('rm', '-r', 'src')
await writeFile(join(repo, 'src'), 'a file now')
await git('add', 'src')
await git('commit', '-m', 'replace folder with file')
await git('switch', 'main')
await expect(prepare('worktree', 'refs/heads/feature', join(repo, 'src')))
.rejects.toMatchObject({ code: 'GIT_PROJECT_UNAVAILABLE' })
})
it('removes a worktree whose checkout hook fails, so a retry starts clean, and logs what the hook said', async () => {
const said = vi.spyOn(console, 'error').mockImplementation(() => {})
const hooks = join(root, 'hooks')
await mkdir(hooks)
await writeFile(join(hooks, 'post-checkout'), '#!/bin/sh\necho "hook refused" >&2\nexit 1\n', { mode: 0o755 })
await git('config', 'core.hooksPath', hooks)
const before = await git('for-each-ref', '--format=%(refname)', 'refs/heads')
await expect(prepare('worktree')).rejects.toMatchObject({ code: 'WORKTREE_FAILED' })
expect(await git('worktree', 'list', '--porcelain')).not.toContain('/worktrees/')
expect(await git('for-each-ref', '--format=%(refname)', 'refs/heads')).toBe(before)
expect(said.mock.calls.map(call => call.join(' ')).join('\n')).toMatch(/\[worktree\] git worktree add failed \(exit 1\).*hook refused/)
expect(await git('branch', '--show-current')).toBe('main')
said.mockRestore()
})
it.each(['No space left on device', 'Disk quota exceeded'])('explains worktree disk exhaustion: %s', async (message) => {
const said = vi.spyOn(console, 'error').mockImplementation(() => {})
const hooks = join(root, 'hooks')
await mkdir(hooks)
await writeFile(join(hooks, 'post-checkout'), `#!/bin/sh\necho 'private-file: ${message}' >&2\nexit 1\n`, { mode: 0o755 })
await git('config', 'core.hooksPath', hooks)
await expect(prepare('worktree')).rejects.toMatchObject({
code: 'WORKTREE_FAILED',
message: 'Not enough disk space to create the worktree. Free space on this machine, then retry.',
})
said.mockRestore()
})
})