Skip to content

A folder inside another repository follows git, a tracked or addable one belonging to the repository and an ignored one being a workspace of its own, for worktrees, the brief and the desktop app's check; and worktree.list answers in bounded time, its status read for two seconds, the checkout first, or not at all with status false

Decision 881 · accepted · 2026-10-12 · issue #650 · supersedes 831, 851

The maintainer's rule (2026-10-12): worktrees and the brief follow git.

The rule. Troupe.Git.ignored?/1 asks git (git check-ignore -q -- ., through Troupe.Git.run/3, so neutralised and confined as every other call). - A folder git does not ignore belongs to the repository around it. That is a folder the repository tracks, and also one it would add (untracked, not ignored: git status names it and git add -A takes it), because git counts both as its working tree and the rule is git's. - A folder git ignores (.gitignore, info/exclude, the person's excludes file, or inside an ignored folder) is a workspace of its own, as a directory in no repository is. The top of a checkout or a worktree is never ignored (git answers 1 for . there), so a linked worktree that sits in its checkout's ignored .worktrees/ is still the repository's, and a nested repository is its own as before. - The check runs only for a folder below git's top level, so a workspace at a checkout's top pays nothing for it; one below pays one check-ignore where it asks where it is.

Where it holds. - The brief. Troupe.Session.Memory.locate/1 (Decision 831's repository root) adds the ignored check to its conditions: an ignored folder's brief, facts and anchors are its own (root and top the folder). Decision 831's rule for a forged .git stands; this adds an ignored folder to its "anything else". repository?/1 now follows locate/1 (the checkout it names has a .git), so refresh_due is false there and no librarian starts by itself; /memory refresh still writes the folder's own brief. It first walks up for a .git as before and runs no git where there is none, so a home directory costs what it did. Onboarding, which asks the same repository?/1, is due nothing in an ignored folder either, and onboard.apply refuses there as it does outside a repository. The instruction files are not part of this: they are still read up to the nearest .git. - worktree.list in an ignored folder answers no rows. In a tracked one it answers the repository's worktrees, as before. - Worktrees.resolve/3 in auto and always: an ignored folder works where it is. A tracked folder's new tree is <checkout>-<slug> beside the checkout (git's top level), never inside it, and the session works in the same folder of the new tree; a folder with nothing committed in it yet is made there, empty. named/2 the same, at <checkout>-<name>; in an ignored folder or in no repository it is refused with invalid_params, field workspace, saying why, where git's own error was answered before. Whether the workspace is busy is still the same directory, not the repository. - Which session a tree is. A row's session_id is the session in the tree's directory, or failing that one in a folder of it git does not ignore, given to the nearest tree that holds it (a checkout that holds its worktrees' directories does not take theirs). A merge, a discard and a named tree's reuse are refused while a session works anywhere in the tree, its folders included, since sessions now start in them.

Bounded time: lazy for those that need no status, bounded for those that do. - status: false answers each row's path, branch and session_id from git's list of the trees alone, with no git per tree. - Otherwise the status is read as Decision 851 reads it (one status --porcelain=v2 and one diff --numstat a tree), but within a budget of two seconds (:worktree_status_ms in the gateway's application environment, a test's knob), eight trees at once, the checkout first, then the trees a session works in, then the rest in git's order; the rows go back in git's order. Each git call a tree runs is given only what is left of the budget, and none starts after it, so the answer comes in about the budget, at worst a few times it when a slow tree was begun just before the end, however many trees there are. list(nil) shares one budget across every live session's workspace. - A row says checked. One the budget did not reach has checked: false with dirty and every count null, never a clean tree's answers; a tree whose status was read but whose diff ran out of time has its counts null and its dirty read. The terminal client draws such a row with no state (not clean), and the desktop app's worktree table says "Not looked at"; its Remove forces only a tree it knows is dirty, and the daemon still refuses a dirty one without force. - Chosen over caching each tree's status (it changes with every edit, so a cache would need an index and mtime check per tree, which is most of the cost on Windows), over a fixed count of trees (a count bounds nothing when one tree is large), and over a separate per-tree status method (both clients would have to fetch row by row; the budget gives the rows that matter at once). Not done: a client cannot ask for the rest later; a refresh reads the same first trees again.

Governs: apps/troupe_core/lib/troupe/git.ex, apps/troupe_core/lib/troupe/session/memory.ex, apps/troupe_core/lib/troupe/memory/facts.ex, apps/troupe_gateway/lib/troupe/gateway/worktrees.ex