fix(worktrees): suppress configured checkout filters

This commit is contained in:
Tianyi Cui committed 2026-10-06 01:39:48 +08:00
1 parent a1e89dd84d
commit 2b6040c40c
11 files changed
+226 -12

No files matched your search

+1
View File
@@ -58,6 +58,7 @@ Creates retained Git worktrees under the mounted filesystem and sandbox provider
/**
* Create a fresh branch and checkout at a pinned local revision, then enter it.
* Existing branches or checkout paths fail. Uncommitted files stay in the source checkout.
* Checkout disables configured clean, smudge, and process filters without changing Git config.
* The new checkout becomes current only after Git setup succeeds. Failures may retain newly
* allocated Git/filesystem artifacts; no branch or checkout is removed automatically.
* @param agent - caller whose current directory selects the source repository and file policy.
+1
View File
@@ -58,6 +58,7 @@ Creates retained Git worktrees under the mounted filesystem and sandbox provider
/**
* Create a fresh branch and checkout at a pinned local revision, then enter it.
* Existing branches or checkout paths fail. Uncommitted files stay in the source checkout.
* Checkout disables configured clean, smudge, and process filters without changing Git config.
* The new checkout becomes current only after Git setup succeeds. Failures may retain newly
* allocated Git/filesystem artifacts; no branch or checkout is removed automatically.
* @param agent - caller whose current directory selects the source repository and file policy.
@@ -15,8 +15,8 @@
en: d152484eb41ac6b4
zh: 2f8a621b991260a1
/deepseek-ai-dsh-experimental-worktree/use-this-package:
en: bde2d1a47e2cbb21
zh: 858d1809d670e6af
en: 70ca6f3e9b8dba85
zh: 19e758cc90bc4047
/deepseek-ai-dsh-experimental-worktree/understand-the-implementation:
en: 6971a7ca9073bef1
zh: b977c28a75c7f963
+1 -1
View File
@@ -32,7 +32,7 @@ Mount the service alongside `workingDirectory`, `fs`, `subprocess`, `sandbox`, a
- name: '@deepseek-ai/dsh-experimental-tool-worktree'
```
`ctx.worktrees.create(agent, { name?, from? }, signal?)` creates a new branch and checkout, then enters the canonical checkout directory through `ctx.workingDirectory.set`. `from` resolves to a local commit before creation and defaults to `HEAD`; staged, unstaged, untracked, and ignored source files are not copied. An existing branch or checkout path is an error. The returned record contains `path`, `branch`, `baseCommit`, and `repositoryRoot`.
`ctx.worktrees.create(agent, { name?, from? }, signal?)` creates a new branch and checkout, then enters the canonical checkout directory through `ctx.workingDirectory.set`. `from` resolves to a local commit before creation and defaults to `HEAD`; staged, unstaged, untracked, and ignored source files are not copied. Checkout disables configured Git clean, smudge, and process filters without changing repository configuration; Git LFS files remain committed pointer files. An existing branch or checkout path is an error. The returned record contains `path`, `branch`, `baseCommit`, and `repositoryRoot`.
The default checkout directory is `<current checkout root>/.agents/worktrees/<name>`. The returned `repositoryRoot` is the top-level directory of the caller’s current checkout; when it is a linked checkout, the pool is nested inside it. Omitted names use `worktree-` plus a UUID. The service writes a `.gitignore` containing `*` and a trailing newline only when its allocation creates the pool; existing files and ignore rules are preserved. Relative `directory`, generated `namePrefix`, executable choices, and process limits are configurable in the [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-experimental-worktree).
+1 -1
View File
@@ -32,7 +32,7 @@ kind: "package-reference"
- name: '@deepseek-ai/dsh-experimental-tool-worktree'
```
`ctx.worktrees.create(agent, { name?, from? }, signal?)` 创建新分支与检出目录,再通过 `ctx.workingDirectory.set` 进入规范化的检出目录。`from` 在创建前解析为本地提交,默认是 `HEAD`;暂存、未暂存、未跟踪以及被忽略的源文件均不复制。分支或检出路径已存在时会报错。返回记录包含 `path`、`branch`、`baseCommit` 和 `repositoryRoot`。
`ctx.worktrees.create(agent, { name?, from? }, signal?)` 创建新分支与检出目录,再通过 `ctx.workingDirectory.set` 进入规范化的检出目录。`from` 在创建前解析为本地提交,默认是 `HEAD`;暂存、未暂存、未跟踪以及被忽略的源文件均不复制。检出操作禁用已配置的 Git clean、smudge 和 process 过滤器,不修改仓库配置;Git LFS 文件保留已提交的指针文件形式。分支或检出路径已存在时会报错。返回记录包含 `path`、`branch`、`baseCommit` 和 `repositoryRoot`。
默认检出目录是 `<current checkout root>/.agents/worktrees/<name>`。返回的 `repositoryRoot` 是调用方当前检出目录的顶层目录;如果它是链接检出目录,工作树父目录就嵌套在其中。省略名称时,使用 `worktree-` 加 UUID。仅当服务的分配操作创建了父目录时,服务才会写入内容为 `*` 加换行符的 `.gitignore`;已有文件与忽略规则保持不变。相对路径 `directory`、生成名称使用的 `namePrefix`、可执行程序与进程限制可在[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-experimental-worktree)中查阅。
+21 -3
View File
@@ -95,6 +95,7 @@ export class WorktreeService extends Service {
/**
* Create a fresh branch and checkout at a pinned local revision, then enter it.
* Existing branches or checkout paths fail. Uncommitted files stay in the source checkout.
* Checkout disables configured clean, smudge, and process filters without changing Git config.
* The new checkout becomes current only after Git setup succeeds. Failures may retain newly
* allocated Git/filesystem artifacts; no branch or checkout is removed automatically.
* @param agent - caller whose current directory selects the source repository and file policy.
@@ -125,10 +126,10 @@ export class WorktreeService extends Service {
private async createCheckout(agent: Agent, { branch, revision }: WorktreeSpec, signal: AbortSignal): Promise<CreatedWorktree> {
const cwd = await this.ctx.workingDirectory.ensure(agent, signal)
const policy = this.ctx.sandboxPolicy.resolve({ session: agent.session })
const run = (directory: string, args: string[], allowedExitCodes?: number[]) => runCommand(
const run = (directory: string, args: string[], allowedExitCodes?: number[], env?: NodeJS.ProcessEnv) => runCommand(
this.ctx, this.config, policy, directory,
[this.config.gitCommand, '--no-lazy-fetch', '-c', 'core.hooksPath=/dev/null', '-c', 'core.fsmonitor=false', ...args],
signal, allowedExitCodes,
signal, allowedExitCodes, env,
)
await run(cwd, ['check-ref-format', `refs/heads/${branch}`])
const rootOutput = await run(cwd, ['rev-parse', '--show-toplevel'])
@@ -147,7 +148,24 @@ export class WorktreeService extends Service {
await runCommand(this.ctx, this.config, policy, repositoryRoot,
[this.config.nodeCommand, '--input-type=module', '-e', PREPARE_DIRECTORY, poolPath, path], signal)
await run(repositoryRoot, ['--work-tree', repositoryRoot, 'worktree', 'add', '--no-checkout', '-b', branch, '--', path, baseCommit])
await run(path, ['--work-tree', path, 'reset', '--hard', '--no-recurse-submodules', baseCommit])
const configured = await run(path, ['config', '--null', '--name-only', '--get-regexp', '^filter\\.'], [0, 1])
const drivers = new Set<string>()
for (const key of configured.stdout.split('\0')) {
const separator = key.lastIndexOf('.')
if (separator > 'filter.'.length && ['clean', 'smudge', 'process', 'required'].includes(key.slice(separator + 1))) {
drivers.add(key.slice('filter.'.length, separator))
}
}
const overrides: NodeJS.ProcessEnv = { GIT_CONFIG_COUNT: String(drivers.size * 4) }
let index = 0
for (const driver of drivers) {
for (const attribute of ['clean', 'smudge', 'process', 'required']) {
overrides[`GIT_CONFIG_KEY_${index}`] = `filter.${driver}.${attribute}`
overrides[`GIT_CONFIG_VALUE_${index}`] = attribute === 'required' ? 'false' : ''
index++
}
}
await run(path, ['--work-tree', path, 'reset', '--hard', '--no-recurse-submodules', baseCommit], undefined, overrides)
const canonicalPath = await this.ctx.workingDirectory.set(agent, path, signal)
return { path: canonicalPath, branch, baseCommit, repositoryRoot }
} catch (error) {
@@ -20,6 +20,7 @@ const GIT_ENV: NodeJS.ProcessEnv = Object.fromEntries([
'GIT_DIR', 'GIT_WORK_TREE', 'GIT_COMMON_DIR', 'GIT_INDEX_FILE', 'GIT_OBJECT_DIRECTORY',
'GIT_ALTERNATE_OBJECT_DIRECTORIES', 'GIT_CONFIG', 'GIT_CONFIG_PARAMETERS', 'GIT_CONFIG_COUNT',
'GIT_CEILING_DIRECTORIES', 'GIT_PREFIX', 'GIT_SHALLOW_FILE', 'GIT_GRAFT_FILE',
'GIT_REPLACE_REF_BASE',
].map(key => [key, undefined]))
/**
@@ -31,6 +32,7 @@ const GIT_ENV: NodeJS.ProcessEnv = Object.fromEntries([
* @param argv - executable followed by literal arguments.
* @param signal - operation cancellation.
* @param allowedExitCodes - command-specific successful statuses.
* @param env - command-local environment overrides, applied after Git selector removal.
* @returns complete bounded stdout and the exit code.
*/
export async function runCommand(
@@ -41,6 +43,7 @@ export async function runCommand(
argv: readonly [string, ...string[]],
signal: AbortSignal,
allowedExitCodes: readonly number[] = [0],
env: NodeJS.ProcessEnv = {},
): Promise<{ stdout: string; exitCode: number }> {
using timeout = deadline(signal, config.timeoutMs, 'WORKTREE_TIMEOUT')
timeout.signal.throwIfAborted()
@@ -53,7 +56,7 @@ export async function runCommand(
const child = ctx.subprocess.spawn({
argv: wrapped,
cwd,
env: { ...GIT_ENV, GIT_TERMINAL_PROMPT: '0', GIT_LFS_SKIP_SMUDGE: '1' },
env: { ...GIT_ENV, GIT_TERMINAL_PROMPT: '0', GIT_LFS_SKIP_SMUDGE: '1', ...env },
signal: timeout.signal,
graceMs: config.graceMs,
stdio: {
@@ -0,0 +1,166 @@
import { access, readFile, rm, writeFile } from 'node:fs/promises'
import { join } from 'node:path'
import { afterEach, describe, expect, it, vi } from 'vitest'
import type { Context } from '@deepseek-ai/cordis'
import { SubprocessExecutableNotFoundError } from '@deepseek-ai/dsh-subprocess'
import { contents, filterCommand, git, harness, repository, testAgent } from './harness.ts'
let ctx: Context | undefined
const roots: string[] = []
afterEach(async () => {
vi.unstubAllEnvs()
await ctx?.fiber.dispose()
ctx = undefined
for (const root of roots.splice(0)) await rm(root, { recursive: true, force: true })
})
async function repo(): Promise<string> {
const root = await repository()
roots.push(root)
return root
}
describe('worktree checkout Git configuration', () => {
it.each(['some.nested.driver', 'x=y', 'lfs'])('disables required clean and smudge filters named %s without changing repository configuration', async (driver) => {
const root = await repo()
const committed = driver === 'lfs'
? `version https://git-lfs.github.com/spec/v1\noid sha256:${'0'.repeat(64)}\nsize 8\n`
: 'initial\n'
await writeFile(join(root, 'tracked.txt'), committed)
await writeFile(join(root, '.gitattributes'), `*.txt filter=${driver} -text\n`)
await git(root, 'add', '.gitattributes', 'tracked.txt')
await git(root, 'commit', '-m', 'attributes')
const { command, marker } = await filterCommand(root)
await git(root, 'config', `filter.${driver}.clean`, command)
await git(root, 'config', `filter.${driver}.smudge`, command)
await git(root, 'config', `filter.${driver}.required`, 'true')
await git(root, 'config', `filter.${driver}.unused`, 'preserved')
const configuration = await readFile(join(root, '.git/config'))
const control = join(root, 'ordinary-checkout')
await git(root, 'worktree', 'add', '-b', 'ordinary', control)
expect(await contents(marker)).toContain('executed')
expect(await contents(join(control, 'tracked.txt'))).toBe(`filtered\n${committed}`)
await rm(marker)
ctx = await harness(root)
const created = await ctx.worktrees.create(testAgent(ctx, root), { name: 'unfiltered' })
await expect(access(marker)).rejects.toMatchObject({ code: 'ENOENT' })
expect(await contents(join(created.path, 'tracked.txt'))).toBe(committed)
expect(await readFile(join(root, '.git/config'))).toEqual(configuration)
})
it('disables a required process filter that makes ordinary checkout fail', async () => {
const root = await repo()
await writeFile(join(root, '.gitattributes'), '*.txt filter=process-driver -text\n')
await git(root, 'add', '.gitattributes')
await git(root, 'commit', '-m', 'attributes')
const { command, marker } = await filterCommand(root, true)
await git(root, 'config', 'filter.process-driver.process', command)
await git(root, 'config', 'filter.process-driver.required', 'true')
const control = join(root, 'ordinary-checkout')
await expect(git(root, 'worktree', 'add', '-b', 'ordinary', control)).rejects.toThrow()
expect(await contents(marker)).toBe('executed\n')
await rm(marker)
ctx = await harness(root)
const created = await ctx.worktrees.create(testAgent(ctx, root), { name: 'unfiltered' })
await expect(access(marker)).rejects.toMatchObject({ code: 'ENOENT' })
expect(await contents(join(created.path, 'tracked.txt'))).toBe('initial\n')
})
it('reports invalid destination-only configuration and retains the unpopulated checkout', async () => {
const root = await repo()
const included = join(root, 'invalid-config')
await writeFile(included, '[invalid configuration\n')
await git(root, 'config', 'includeIf.onbranch:invalid.path', included)
ctx = await harness(root)
const agent = testAgent(ctx, root)
await expect(ctx.worktrees.create(agent, { name: 'invalid' })).rejects.toThrow(/Any created checkout and branch are retained.*bad config line/s)
expect(ctx.workingDirectory.get(agent.session)).toBe(root)
await access(join(root, '.agents/worktrees/invalid/.git'))
await expect(access(join(root, '.agents/worktrees/invalid/tracked.txt'))).rejects.toMatchObject({ code: 'ENOENT' })
expect(await git(root, 'branch', '--list', 'invalid')).toContain('invalid')
})
it('refuses truncated destination filter configuration before materializing files', async () => {
const root = await repo()
await git(root, 'config', `filter.${'long-driver-'.repeat(100)}.smudge`, 'unavailable-filter')
ctx = await harness(root, { maxOutputBytes: 256 })
const agent = testAgent(ctx, root)
await expect(ctx.worktrees.create(agent, { name: 'bounded' })).rejects.toThrow('output exceeds maxOutputBytes')
expect(ctx.workingDirectory.get(agent.session)).toBe(root)
await access(join(root, '.agents/worktrees/bounded/.git'))
await expect(access(join(root, '.agents/worktrees/bounded/tracked.txt'))).rejects.toMatchObject({ code: 'ENOENT' })
})
it('discovers filters selected only by the newly created branch', async () => {
const root = await repo()
await writeFile(join(root, '.gitattributes'), '*.txt filter=destination-only -text\n')
await git(root, 'add', '.gitattributes')
await git(root, 'commit', '-m', 'attributes')
const { command, marker } = await filterCommand(root)
const included = join(root, 'destination-config')
await git(root, 'config', '--file', included, 'filter.destination-only.smudge', command)
await git(root, 'config', '--file', included, 'filter.destination-only.required', 'true')
await git(root, 'config', 'includeIf.onbranch:destination.path', included)
await expect(git(root, 'config', '--get-regexp', '^filter\\.')).rejects.toMatchObject({ code: 1 })
ctx = await harness(root)
const created = await ctx.worktrees.create(testAgent(ctx, root), { name: 'destination' })
expect(await git(created.path, 'config', 'filter.destination-only.smudge')).toBe(command)
await expect(access(marker)).rejects.toMatchObject({ code: 'ENOENT' })
expect(await contents(join(created.path, 'tracked.txt'))).toBe('initial\n')
})
it('ignores inherited repository, replacement-ref and command-config selectors', async () => {
const root = await repo()
const other = await repo()
const baseCommit = await git(root, 'rev-parse', 'HEAD')
await git(root, 'checkout', '-b', 'replacement')
await writeFile(join(root, 'tracked.txt'), 'redirected\n')
await git(root, 'commit', '-am', 'replacement')
const replacement = await git(root, 'rev-parse', 'HEAD')
await git(root, 'checkout', 'main')
await git(root, 'update-ref', `refs/alternate-replacements/${baseCommit}`, replacement)
ctx = await harness(root)
const agent = testAgent(ctx, root)
vi.stubEnv('GIT_DIR', join(other, '.git'))
vi.stubEnv('GIT_WORK_TREE', other)
vi.stubEnv('GIT_COMMON_DIR', join(other, '.git'))
vi.stubEnv('GIT_INDEX_FILE', join(other, '.git/index'))
vi.stubEnv('GIT_OBJECT_DIRECTORY', join(other, '.git/objects'))
vi.stubEnv('GIT_IMPLICIT_WORK_TREE', '0')
vi.stubEnv('GIT_REPLACE_REF_BASE', 'refs/alternate-replacements/')
vi.stubEnv('GIT_CONFIG_COUNT', '1')
vi.stubEnv('GIT_CONFIG_KEY_0', 'core.bare')
vi.stubEnv('GIT_CONFIG_VALUE_0', 'true')
const created = await ctx.worktrees.create(agent, { name: 'selected' })
expect(created.repositoryRoot).toBe(root)
expect(created.baseCommit).toBe(baseCommit)
expect(await contents(join(created.path, 'tracked.txt'))).toBe('initial\n')
expect(await git(other, 'branch', '--list', 'selected')).toBe('')
})
it('reports a missing Git executable before allocating a checkout', async () => {
const root = await repo()
ctx = await harness(root, { gitCommand: join(root, 'unavailable-git') })
const agent = testAgent(ctx, root)
await expect(ctx.worktrees.create(agent, { name: 'unavailable' })).rejects.toBeInstanceOf(SubprocessExecutableNotFoundError)
expect(ctx.workingDirectory.get(agent.session)).toBe(root)
await expect(access(join(root, '.agents/worktrees'))).rejects.toMatchObject({ code: 'ENOENT' })
expect(await git(root, 'branch', '--list', 'unavailable')).toBe('')
})
})
@@ -91,3 +91,21 @@ export async function harness(root: string, config: Config = {}, mode: SandboxMo
export async function contents(path: string): Promise<string> {
return readFile(path, 'utf8')
}
/**
* Create a filter whose file marker and transformed output reveal its execution.
* @param root - the owning test's private repository directory.
* @param processFilter - fail the process-filter handshake instead of transforming stdin.
* @returns a Git shell command and the marker it writes.
*/
export async function filterCommand(root: string, processFilter = false): Promise<{ command: string; marker: string }> {
const script = join(root, 'filter.cjs')
const marker = join(root, 'filter-executed')
await writeFile(script, `
const fs = require('node:fs');
fs.appendFileSync(${JSON.stringify(marker)}, 'executed\\n');
${processFilter ? 'process.exit(1);' : "process.stdout.write('filtered\\n' + fs.readFileSync(0, 'utf8'));"}
`)
const quoted = (value: string) => `'${value.replaceAll('\\', '/').replaceAll("'", "'\\''")}'`
return { command: `${quoted(process.execPath)} ${quoted(script)}`, marker }
}
@@ -1,10 +1,10 @@
import { mkdir, readFile, readdir, rm } from 'node:fs/promises'
import { access, mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises'
import { join } from 'node:path'
import { afterEach, describe, expect, it, vi } from 'vitest'
import { Context } from '@deepseek-ai/cordis'
import { SandboxUnavailableError } from '@deepseek-ai/dsh-sandbox'
import LocalSandbox from '@deepseek-ai/dsh-sandbox-local'
import { git, harness, repository, testAgent } from './harness.ts'
import { filterCommand, git, harness, repository, testAgent } from './harness.ts'
let ctx: Context | undefined
let root: string | undefined
@@ -49,8 +49,14 @@ describe.skipIf(!sandboxUsable)('worktree standing sandbox policy', () => {
expect(confine.mock.calls.every(call => call[1].mode === 'read-only' && call[1].workspaceRoot === root)).toBe(true)
})
it('creates a checkout in the default pool under the source workspace-write grant', async () => {
it('creates an unfiltered checkout in the default pool under the source workspace-write grant', async () => {
root = await repository(process.cwd())
await writeFile(join(root, '.gitattributes'), '*.txt filter=configured -text\n')
await git(root, 'add', '.gitattributes')
await git(root, 'commit', '-m', 'attributes')
const { command, marker } = await filterCommand(root)
await git(root, 'config', 'filter.configured.smudge', command)
await git(root, 'config', 'filter.configured.required', 'true')
ctx = await harness(root, {}, 'workspace-write')
const agent = testAgent(ctx, root)
const confine = vi.spyOn(ctx.sandbox, 'confine')
@@ -58,6 +64,7 @@ describe.skipIf(!sandboxUsable)('worktree standing sandbox policy', () => {
const checkout = join(root, '.agents', 'worktrees', 'allowed')
expect(created.path).toBe(checkout)
await expect(access(marker)).rejects.toMatchObject({ code: 'ENOENT' })
expect(await readFile(join(checkout, 'tracked.txt'), 'utf8')).toBe('initial\n')
expect(await git(checkout, 'branch', '--show-current')).toBe('allowed')
expect(await git(root, 'branch', '--show-current')).toBe('main')
@@ -3836,7 +3836,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
methods: [
{
signature: 'async create(agent: Agent, request: CreateWorktreeRequest = {}, signal?: AbortSignal): Promise<CreatedWorktree>',
description: 'Create a fresh branch and checkout at a pinned local revision, then enter it. Existing branches or checkout paths fail. Uncommitted files stay in the source checkout. The new checkout becomes current only after Git setup succeeds. Failures may retain newly allocated Git/filesystem artifacts; no branch or checkout is removed automatically.',
description: 'Create a fresh branch and checkout at a pinned local revision, then enter it. Existing branches or checkout paths fail. Uncommitted files stay in the source checkout. Checkout disables configured clean, smudge, and process filters without changing Git config. The new checkout becomes current only after Git setup succeeds. Failures may retain newly allocated Git/filesystem artifacts; no branch or checkout is removed automatically.',
parameters: [{ name: 'agent', description: 'caller whose current directory selects the source repository and file policy.' }, { name: 'request', description: 'optional new name and local revision; defaults are generated name and HEAD.' }, { name: 'signal', description: 'cancellation of lookup, creation, and working-directory publication.' }],
returns: 'canonical checkout path, branch name, pinned commit, and source repository root.',
},