Every git Troupe runs for itself in a workspace runs nothing the repository's own .git names and reads only the checkout's own repository, and the file tools never write under .git¶
Decision 833 · accepted · 2026-10-10 · issue #529
Superseded in part
In part by 858.
Troupe runs git for its own purposes in a session's workspace, outside the sandbox: the
git_read tool, which runs without asking by default; the project brief's repository,
HEAD and file count, the first of them before every model call; the files a worktree's
checkout commits (Decision 826); and the gateway's worktrees (Decision 647). git honours
settings in the repository's own .git, and some of them run a command. A session's agent
can write that directory (through the file tools until now, through the shell still), so
it could have Troupe's own git run a command outside the sandbox: as the daemon, or on a
pod as the worker, beside the other sessions' workspaces. A .git naming another
checkout's repository as its common directory also let git_read read that checkout's
history (#529).
One runner. Troupe.Git.run/3 is how Troupe runs git in a workspace: git_read,
Troupe.Session.Memory, Troupe.Worktree and Troupe.Gateway.Worktrees all call it. It
answers what Troupe.Reaper.run/3 answers, so the callers keep their shape, and a reaper
that will not start is still an error, never a raise (Decision 733).
What is neutralised, and why each.
core.fsmonitor=false. The fsmonitor hook runs in any command that reads the index:status,diff,ls-files(the brief's file count).core.hooksPathset to a path inside the reaper helper, which is a file, so no directory can be there and no hook runs.statuscan write the index and so runpost-index-change; a ref update runsreference-transaction; the gateway's worktree runspost-checkout, its commit and mergepre-commit,commit-msg,post-commit,pre-merge-commitandpost-merge./dev/nullis the usual value, but on Windows it means\dev\nullon the current drive, where a directory of that name can be made.- The repository's own filters,
filter.<name>.clean,smudgeandprocessfrom thelocalandworktreescopes ofgit config --list --show-scope, get an empty command, which git reads as none, andrequired=false.statusanddiffhash a changed file through its clean filter, and a checkout writes through its smudge filter. Filters in the person's own config and the machine's (git-lfs, typically) are theirs, and run. A command that reads only refs and objects (rev-parse,ls-tree,log,show,branch) applies no filter, so for those the config is not listed first. - The repository's own merge drivers,
merge.<name>.driver, becomefalse. A file one of them would have merged is a conflict, and the gateway's merge is aborted as on any conflict (Decision 647), for the person to merge. An empty driver would run an empty command and silently keep one side. --no-textconvand--no-ext-diffondiff,showandlog. Adiff.<name>.textconv,diff.<name>.commandordiff.externalruns a command for each file a diff shows. The flags turn the person's own off too (a configured external diff, Git for Windows'astextplain): what a tool reads is the bytes.--ignore-submodules=dirtyonstatusanddiff. Looking inside a submodule runs git there, under the submodule's own config, which the runner has not read. A submodule now shows when its commit moves, not when its files change.submodule.recurse=false,gc.auto=0andmaintenance.auto=false. No command recurses into a submodule, and the gateway's commit and merge leave no gc running after them.commit.gpgSign=false,merge.verifySignatures=falseandlog.showSignature=false. Signing and checking a signature rungpg.programorgpg.ssh.program, which the repository's config can name. The gateway's own commits are not signed.safe.bareRepository=explicit. A workspace laid out as a bare repository is not taken for one.--no-pager, andGIT_EDITOR=:, git's own word for no editor.core.pagerandcore.editornever start.- No transport:
GIT_ALLOW_PROTOCOL=noneandGIT_NO_LAZY_FETCH=1, withGIT_TERMINAL_PROMPT=0. Nothing here fetches, but a partial clone fetches a missing object when a command needs it, through the remote the repository names, and so could startcore.sshCommand, a credential helper, a remote'suploadpackor anext::command. GIT_OPTIONAL_LOCKS=0.statusdoes not write the index back, so a read stays a read.- No
GIT_*variable of the daemon's own. AGIT_DIR,GIT_CONFIG_PARAMETERSorGIT_EXTERNAL_DIFFin the environment the daemon was started from is taken away (Troupe.Reapernow takes away a variable given asnil). - The settings travel as
GIT_CONFIG_PARAMETERS, the waygit -cpasses its own to the commands it starts, so they hold in git's children too, with each name and value quoted as git quotes them. A filter nameda=b'cis one that-c filter.a=b'c.clean=would cut short, and an empty value is one a port cannot set as a variable of its own (GIT_CONFIG_VALUE_<n>).
Not set: GIT_CONFIG_NOSYSTEM. It was considered and left out. The machine's file is
not the session's to write, so ignoring it guards nothing, and on Windows it is where Git for
Windows keeps core.autocrlf=true and the git-lfs filter: without them a CRLF checkout's
changed file reads as every line changed, and a large file as its pointer. The person's
global file is read for the same reason (safe.directory lives there too).
Where git may read. git finds the repository as it always has (rev-parse
--is-inside-work-tree --show-toplevel --git-dir --git-common-dir), and the command runs
only when
- the workspace is in git's working tree, so a
core.worktreepointing elsewhere is not followed; - the common directory is the
.gitof the checkout: git's top level, or the main checkout that a worktree's.gitnames and that names the worktree back (Troupe.Config.Trust.root/1, the check trust,Troupe.Worktree.main/1and Decision 831 make); - the git directory is that
.gititself or, for such a worktree, one of the checkout's.git/worktrees/.
Real paths throughout, so a .git that is a link out is not followed. A workspace in a
subdirectory of a checkout reads the checkout, as before, and a real worktree reads its
checkout's history. The command then runs with GIT_DIR, GIT_COMMON_DIR and
GIT_WORK_TREE set to what was checked, so a .git rewritten in between does not move
it. Anything else is not read: git_read answers "git was not run: ..." and names the
directory, the brief takes the workspace for no repository (its brief is then its own,
as Decision 831 has it, and stamped with no HEAD), and the gateway makes no worktree
there. A session opened in a submodule's own directory, whose git directory is in the
superproject's .git/modules/, is refused the same way.
The file tools. Troupe.Workspace.resolve/3 and Troupe.Mounts.resolve/3 refuse a
write to a path in a .git directory, or to a .git file, judged where the path really
is (Troupe.Workspace.git_dir?/2): so write_file, edit_file, import, an ACP agent's
fs/write_text_file and a client's fs.upload all refuse it, with a sentence saying why.
.git is matched in the spellings git itself refuses in a tree: any case, trailing dots
or spaces and a stream name (NTFS), the short name git~1, and the code points HFS+
ignores. Troupe.Onboard.check_path/2 refuses such a path for onboard_write and troupe
onboard. The shell can still write there, which is why the runner does not rely on this.
Not covered.
- Objects reached through
objects/info/alternates, or through a link inside.git(objects, a pack): git reads them where they point. On a pod, the way to close that and the rest of this class is to run Troupe's own git inside the session's sandbox, the issue's other option, not taken here. Decision 858 now refuses such a repository. git worktree removewithout--forcechecks the worktree itself, withstatus --ignore-submodules=none, so a submodule in a worktree being removed is looked inside under its own config.- The cost: one or two more git processes for each call (where the repository is, and its config for a command that touches the working tree).
Governs: apps/troupe_core/lib/troupe/git.ex, apps/troupe_core/lib/troupe/tools/git_read.ex, apps/troupe_core/lib/troupe/session/memory.ex, apps/troupe_core/lib/troupe/worktree.ex, apps/troupe_core/lib/troupe/workspace.ex, apps/troupe_core/lib/troupe/mounts.ex, apps/troupe_core/lib/troupe/onboard.ex, apps/troupe_gateway/lib/troupe/gateway/worktrees.ex