# .fossil-settings/

## Purpose

Versioned fossil settings (one setting value or glob list per file) for this dual-VCS tree: git and fossil both track the same project. This file is also the canonical home of the git+fossil coexistence contract, including the rules for keeping `.gitignore` and `ignore-glob` in sync.

## Ownership

- `.gitignore` is the canonical statement of ignore intent; `ignore-glob` is hand-derived from it per the rules below - never the other direction.
- `.fossil-settings/` and `.fossil-custom/` are git-tracked (versioned fossil config rides in git even at sites where fossil is unused).

## Local Contracts

### Commit warning suppression

- `binary-glob` is `*`: binary checkins are allowed by default with no fossil warnings/prompts (applies to punkshell and is the pattern for sub-projects like tomlish). The aim of an eventually binary-free tree (goals G-004/G-005/G-006) is agent/workflow policy (see root `AGENTS.md` User Preferences) and is deliberately NOT enforced at the local VCS layer.

### Files each system must not track

- **Fossil-generated checkout artifacts**: the `manifest` setting (value `rut`) makes fossil regenerate `manifest`, `manifest.uuid` and `manifest.tags` at the checkout root on every checkin/checkout. Fossil auto-manages them (they never appear in extras and cannot be added). Git must ignore them - root-anchored `/manifest`, `/manifest.uuid`, `/manifest.tags` in `.gitignore` (anchored because nested manifest-named files elsewhere are real content) - and must never track them.
- **Fossil control files**: `.fslckout` / `_FOSSIL_` (checkout db), `*.fossil` (repository db) - git-ignored; fossil auto-ignores its own.
- **Git control tree**: `.git` stays in `ignore-glob`. Fossil skips dot-prefixed names by default, but an `addremove --dotfiles` scan would otherwise descend into it.
- Git meta files that are project content (`.gitignore`, `.gitkeep` placeholders) ARE fossil-tracked for mirror completeness - capture them with `--dotfiles` on addremove/add scans.

### ignore-glob derivation rules (verified against fossil 2.28)

- **No negation exists in fossil globs.** Git's `/bin/*` + `!exception` pattern becomes: ignore `bin/*` wholesale and explicitly `fossil add` the tracked exceptions (ignore-glob never affects already-managed files, so they stay tracked). The exception set is whatever git tracks under an ignored tree - at the time of writing: `bin/AGENTS.md`, `bin/*.cmd`, `bin/*.kit`, `bin/*.tcl`, `bin/*.sh`, `bin/*.bash`, `.claude/settings.json` (shared claude harness hooks/permissions; session-local `.claude` files stay ignored), plus force-tracked one-offs (`bin/libssp-0.dll`, `src/vfs/punk9magicsplat.vfs/lib/nmake/x86_64-w64-mingw32-nmakehlp.exe`). Derive the current set with the verification comparison below rather than trusting this list.
- A bare directory name prunes that whole tree; `*` crosses `/`; git patterns intended to match at any depth need an additional `*/` variant; `#` comment lines are honoured.
- Do not add the fossil-generated names (`manifest`, `manifest.uuid`, `manifest.tags`) to `ignore-glob` - fossil handles them itself.
- **Nested `.gitignore` files are git-only**: ignore files inside subtrees (e.g. the project-layout templates under `src/project_layouts/`) are honoured by git as nested ignores of the outer repo but invisible to fossil - template content they match is untracked in git yet managed by fossil. Treat such divergence as a signal to review the git side (usually `git add -f` of the affected template files).
- **Case sensitivity differs**: git ignore matching is case-insensitive on Windows (`core.ignorecase`), fossil glob matching is case-sensitive - e.g. a `todo.txt` pattern hits vendored `TODO.txt` in git but not fossil.

### Safe sync procedure (when asked to "sync the ignores")

1. Edit `.gitignore` first (canonical), then hand-translate to `ignore-glob` using the rules above. Never translate a negation literally.
2. Verify from the checkout root:
   - `fossil extras | git check-ignore --stdin` must output **nothing** (fossil is not under-ignoring relative to git).
   - Git-tracked files invisible to fossil must reduce to the documented exception set plus the fossil-generated manifests: compare `git ls-files | sort` against `(fossil ls; fossil extras) | sort` (beware false diffs from case and non-ASCII path encoding).
3. A fossil `addremove` after a glob change should use `--dotfiles` and be reviewed before commit; pending adds captured under older globs are stale - `fossil revert` cancels uncommitted adds without touching file content when nothing is committed on top of them.

## Work Guidance

## Verification

- `fossil extras | git check-ignore --stdin` → empty
- `git ls-files | sort` vs `(fossil ls; fossil extras) | sort` → differences limited to the documented exception set + fossil-generated manifests

## Child DOX Index

(none)