Skip to content

Commit a8baa5f

Browse files
authored
Merge pull request DeusData#1131 from gandie/docs/mention-ignore-opt-in
Mention un-skip option in docs
2 parents 4573a51 + 45c9b62 commit a8baa5f

1 file changed

Lines changed: 20 additions & 24 deletions

File tree

‎docs/cbmignore.md‎

Lines changed: 20 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -63,20 +63,25 @@ snapshots/
6363

6464
## Precedence
6565

66-
Discovery applies its filters in a fixed order — the first layer that rejects
67-
a path wins. For directories:
66+
Discovery applies its filters in a fixed order. In general, the first layer
67+
that rejects a path wins, except `.cbmignore` negations (layer 4) can un-skip
68+
ordinary built-in skip directories from layer 1 and rescue paths from layer 5.
69+
For directories:
6870

6971
1. **Built-in skip list** — `.git`, `node_modules`, `dist`, `target`,
7072
`vendor`, tool caches, etc. (60+ names; the fast/moderate index modes add
71-
more, e.g. `docs`, `examples`, `testdata`). Not overridable from any
72-
ignore file today.
73+
more, e.g. `docs`, `examples`, `testdata`). A `.cbmignore` negation
74+
(for example `!target/`) can un-skip these directories, except the
75+
non-negatable safety core: `.git`, `node_modules`, `.worktrees`, and
76+
`.claude-worktrees`.
7377
2. **Repo `.gitignore`** — `<repo>/.gitignore` merged with
7478
`<git-common-dir>/info/exclude` (worktree-aware); later patterns win on
7579
conflict. Honored even when the indexed directory is not a git repo root.
7680
3. **Nested `.gitignore` files** — picked up during the walk and matched
7781
relative to their own directory.
7882
4. **`.cbmignore`** — a positive match skips the path; a negated match can
79-
only rescue paths from layer 5.
83+
un-skip built-in skip dirs from layer 1 (except the safety core) and can
84+
also rescue paths from layer 5.
8085
5. **Git global excludes** — `core.excludesFile` from `~/.gitconfig` or the
8186
XDG git config (default `$XDG_CONFIG_HOME/git/ignore`); consulted only
8287
when the project is a git repo with a config.
@@ -97,25 +102,16 @@ always skipped.
97102
directory is excluded. Negate the directory itself if you need its
98103
contents.
99104
- **Across layers**: a `.cbmignore` negation overrides the **git global
100-
excludes** layer only. Example: your `~/.config/git/ignore` ignores
101-
`*.sql`, but this project's SQL should be indexed — add `!*.sql` to
102-
`.cbmignore`. Negation cannot override the built-in skip lists, the repo
103-
`.gitignore`/`info/exclude`, nested `.gitignore` files, the built-in
104-
suffix/filename filters, or the size cap.
105-
106-
### Planned (not yet implemented)
107-
108-
The negation story is being unified; none of the following works yet:
109-
110-
- `!` in `.cbmignore` will be able to un-skip ordinary built-in skip
111-
directories (`obj/`, `dist/`, `target/`, …) so build-output-like
112-
directories that actually contain source can be indexed.
113-
- A small safety core stays non-negatable by design — `.git`,
114-
`node_modules`, and worktree-internal directories — because indexing them
115-
risks OOM and correctness issues (see issue #489).
105+
excludes** layer and can also un-skip ordinary built-in skip directories.
106+
Example: your `~/.config/git/ignore` ignores `*.sql`, but this project's
107+
SQL should be indexed — add `!*.sql` to `.cbmignore`. Negation still cannot
108+
override the safety core built-in dirs (`.git`, `node_modules`,
109+
`.worktrees`, `.claude-worktrees`), the repo `.gitignore`/`info/exclude`,
110+
nested `.gitignore` files, the built-in suffix/filename filters, or the
111+
size cap.
112+
113+
### Planned follow-up
114+
116115
- Auxiliary filesystem walkers will honor the same ignore predicate as
117116
discovery, so every code path sees an identical ignore decision
118117
(unification tracked in a follow-up issue).
119-
120-
Until these land, the "Precedence" and "Negation — current behavior" sections
121-
above describe the actual behavior.

0 commit comments

Comments
 (0)