[Bug]: No documented way to exclude directories from the workspace index; `.gitignore` does not apply outside a git repository

[JoergHansmann]

The situation

On a large workspace the index scan exceeds the hardcoded 15-second deadline and the
Files panel fails completely (reported separately). The natural user response is to
exclude directories that carry no useful content. There is no supported way to do that.

• The built-in exclusion list is fixed: node_modules, __pycache__, venv, .venv,
  target/debug, target/release, target/rust-analyzer, target/criterion.
• Nothing in Settings, settings.json or client-settings.json adds to it.
• .gitignore is honored by the underlying ignore crate only inside a git
  repository. Workspaces that are Subversion working copies, plain directories, or
  anything else non-git get no benefit from it.
• .ignore works, and a custom filename .jj.ignore appears to be registered as well,
  but neither is mentioned anywhere in docs/user/. I only found them by reading strings
  in fff_c.dll.

So the mechanism largely exists; it is simply undiscoverable, and the one file name most
users would reach for is the one that silently does nothing for them.

Measurements from a real workspace

Windows 10, local NTFS, Subversion working copy, T3 Code 0.0.40.

Level	Files
Total in tree	655098
Under node_modules (already excluded by T3)	478681
Effectively scanned	146377
Of which .svn	7913

Adding common build and VCS output directories (build/, .gradle/, platforms/,
obj/, bin/, Library/, Temp/, packages/, .git/) to an ignore file brings the
walked tree to 93482 files. The index scan then completed in 1503 ms instead of hitting
the 15-second deadline.

One caveat on that number, because it would be easy to over-read: the OS
directory-metadata cache was warm when it was taken. An equivalent walk over the same
tree took 100.8 s cold against 9.9 s warm, so cache state is worth about a factor of ten
here and the exclusion list about a factor of three. The exclusions are a real
improvement, but they are not by themselves the difference between 15028 ms and 1503 ms.

Two suggestions

1. Document the ignore-file mechanism in docs/user/. State which file names are
   read, and state clearly that .gitignore requires a git repository. This alone would
   have saved the whole investigation.
2. Add .svn and .hg to the built-in list. Both hold VCS metadata plus, in
   Subversion's case since 1.7, a pristine duplicate of the working tree. It is 5 % here
   rather than the dominant cost, so this is a small win, not a fix — but it is content
   that can never be wanted.

A third option worth considering is honoring .gitignore regardless of whether a git
repository is present, since in a T3 workspace the file expresses intent about the
directory either way.

Environment

• T3 Code 0.0.40 (Alpha), installed via winget install T3Tools.T3Code
• Windows 10 Home 19045
• Workspace is a Subversion working copy, not a git repository

[juliusmarminge]

Triage

Confirmed, not a duplicate of #10917. That issue is the hardcoded 15s scan timeout failing projects.listEntries. This one is the missing, undocumented way to shrink what the index walks — especially outside Git.

What the tree actually does

The Files panel, @ picker, and workspace search all go through WorkspaceEntries → WorkspaceSearchIndex → @ff-labs/fff-node@0.9.4. T3 creates the finder with no ignore/exclude options:

FileFinder.create({
  basePath: cwd,
  disableMmapCache: true,
  disableContentIndexing: variant !== "content",
  aiMode: false,
  enableFsRootScanning: true,
  enableHomeDirScanning: true,
})

There is no setting in Settings, settings.json, client-settings.json, or t3.json. projects.listEntries accepts only { cwd }.

Built-in skips are a fixed list in FFF 0.9.4 (crates/fff-core/src/ignore.rs): node_modules, __pycache__, venv, .venv, target/debug, target/release, target/rust-analyzer, target/criterion, plus some Windows/macOS machine-state paths. T3 does not extend it. Current FFF main still does not include .svn or .hg.

Ignore files

FFF’s walker is the ignore crate (0.4.25 in FFF 0.9.4):

• .gitignore / .git/info/exclude / global gitignore apply only inside a Git (or Jujutsu .jj) root. A Subversion WC or plain directory gets no benefit. That is crate semantics, not a T3 wiring bug.
• .ignore is always read (WalkBuilder.ignore(true)), same syntax as gitignore, and does not require Git. The reporter’s reduction (146k → 93k) is this path.
• .jj.ignore is not registered as a custom filename in FFF 0.9.4. The crate treats a .jj directory as a VCS root so .gitignore applies there. Jujutsu itself still uses .gitignore.

None of this is documented in docs/user/. FFF’s own README mentions .ignore; T3’s user docs do not.

On adding .svn / .hg

For a non-Git root FFF also sets .hidden(true), so dot-directories such as .svn should already be skipped (same walker condition as #8665). The 7,913 .svn files in the report look like an independent tree walk after subtracting node_modules, not a confirmed index inclusion. The reporter already notes this is ~5% and not the dominant cost. Adding .svn/.hg to the built-in list is still reasonable defense-in-depth; the user-facing fix is documenting .ignore for build/, obj/, bin/, platforms/, and similar.

Not a duplicate

Issue / PR	Why it is related but distinct
#10917	Timeout / hard fail. Same workspace; different fix.
#4640	Silent 25k truncation on the same index.
#8665 / #8670	Non-Git dot-entries hidden by .hidden(!is_git_repo).
#10628 / #10686	Non-Git binaries dropped by FFF 0.9.4; open FFF 0.10.6 bump.
#10380	Opposite knob: show gitignored files.
#2077 / #2078	Historical @ search gitignore wiring (pre-FFF). Closed.
#7088	Usage transcript walk, not the workspace index.

No merged fix. Open PRs above do not document ignore files or add user excludes.

Workaround

Add a .ignore file at the workspace root (gitignore syntax). Example for this report:

.svn/
.hg/
build/
.gradle/
platforms/
obj/
bin/

Restart or refresh Files so the index rebuilds. .gitignore in the same place will not help until the folder is a Git (or .jj) repo.

Next step

1. Document the ignore-file mechanism in docs/user/ (which names are read; that .gitignore needs a Git/Jujutsu root; that .ignore is the supported extra file).
2. Optionally ask FFF to add .svn/.hg to the built-in list, and/or honor .gitignore without a Git root. T3 0.9.4 has no API to pass extra patterns today.
3. Do not wait on [Bug]: Workspace index scan timeout of 15s is hardcoded and fails the whole Files panel with no partial result #10917, fix(server): list binary files outside Git repositories #10686, or feat(files): add a setting to show gitignored files #10380.

Labels: documentation, enhancement, accepted, via-triage; remove needs-triage.