From fc537c9456a78846c8811961f7472b8f9b6c5a4f Mon Sep 17 00:00:00 2001 From: Julian Noble Date: Mon, 6 Jul 2026 00:59:19 +1000 Subject: [PATCH] dual-VCS coexistence contract: untrack fossil-generated manifests, add .fossil-settings/AGENTS.md git tracked fossil's generated checkout artifacts (manifest, manifest.tags, manifest.uuid - regenerated on every fossil checkin/checkout per the versioned 'manifest' setting value 'rut'), which would churn as soon as fossil commits begin. They are now untracked and git-ignored with root-anchored patterns (nested manifest-named files elsewhere are real content and stay tracked). Fossil control files (.fslckout/_FOSSIL_/ *.fossil) were already correctly git-ignored, and .fossil-settings/ .fossil-custom correctly git-tracked. New .fossil-settings/AGENTS.md is the canonical home of the git+fossil contract: which files each system must not track, the ignore-glob derivation rules (no negation -> wholesale-ignore + explicit fossil add of tracked exceptions; directory pruning; * crossing /; */ variants for match-anywhere patterns; default dotfile skipping), and the verification procedure any future "sync the ignores" request must follow (fossil extras against git check-ignore, and a tracked-set comparison bounded to the documented exceptions). The ignore-glob header now points there instead of duplicating the rules; root AGENTS.md Child DOX Index gains the entry. Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com --- .fossil-settings/AGENTS.md | 44 ++++++++++++++++++++++++++++++++++++ .fossil-settings/ignore-glob | 9 +++----- .gitignore | 8 +++++++ AGENTS.md | 1 + manifest | 8 ------- manifest.tags | 2 -- manifest.uuid | 1 - 7 files changed, 56 insertions(+), 17 deletions(-) create mode 100644 .fossil-settings/AGENTS.md delete mode 100644 manifest delete mode 100644 manifest.tags delete mode 100644 manifest.uuid diff --git a/.fossil-settings/AGENTS.md b/.fossil-settings/AGENTS.md new file mode 100644 index 00000000..9863a15f --- /dev/null +++ b/.fossil-settings/AGENTS.md @@ -0,0 +1,44 @@ +# .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 + +### 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`, 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. + +### 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) diff --git a/.fossil-settings/ignore-glob b/.fossil-settings/ignore-glob index 5a71f72f..f3a06eef 100644 --- a/.fossil-settings/ignore-glob +++ b/.fossil-settings/ignore-glob @@ -1,10 +1,7 @@ #Derived from .gitignore (the canonical statement of ignore intent) - keep in sync manually. -#Fossil glob semantics differ from git (verified fossil 2.28): -# - no negation patterns: the tracked exceptions under bin/ (AGENTS.md, *.cmd, *.kit, *.tcl, -# *.sh, *.bash) cannot be expressed - bin/* is ignored wholesale and source-controlled bin -# items must be explicitly 'fossil add'ed (ignore-glob does not affect already-managed files) -# - a bare directory name prunes the whole tree; * crosses directory separators -# - git patterns intended to match at any depth need an additional */ variant here +#See .fossil-settings/AGENTS.md for the git+fossil coexistence contract: the glob semantic +#translation rules (fossil has no negation - bin/* is wholesale-ignored with the tracked +#exceptions handled by explicit 'fossil add'), and the verification procedure for syncing. .git CVS diff --git a/.gitignore b/.gitignore index 565334d5..fefe5f42 100644 --- a/.gitignore +++ b/.gitignore @@ -64,6 +64,14 @@ _FOSSIL_ .fslckout *.fossil +#fossil-generated checkout artifacts - regenerated on every fossil checkin/checkout per the +#versioned 'manifest' setting (value 'rut'); fossil auto-manages them and they must not be +#git-tracked. Anchored: nested manifest-named files elsewhere are real content. +#See .fossil-settings/AGENTS.md for the git+fossil coexistence contract. +/manifest +/manifest.uuid +/manifest.tags + #miscellaneous editor files etc *.swp *.log diff --git a/AGENTS.md b/AGENTS.md index f41c9c6b..05bc48df 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -138,6 +138,7 @@ When the user requests a durable behavior change, record it here or in the relev - `src/doc/` — Generated documentation (see src/doc/AGENTS.md) - `src/testansi/` — Sample ANSI art files (do not modify) - `bin/` — Built punk shell executables, launch package modes (incl. `src` mode for working-tree verification), plain runtime kits (see bin/AGENTS.md) +- `.fossil-settings/` — Versioned fossil settings and the git+fossil dual-VCS coexistence contract: ignore-sync rules, files neither system may track (see .fossil-settings/AGENTS.md) - `GOALS.md` — Top-level technical goal index; required read for non-trivial work (no child AGENTS.md; the file documents its own format and the agent goal-authoring workflow) - `GOALS-archive.md` — One-line records of achieved goals moved out of the active index (historical context only) - `goals/` — Optional detail prose for goals needing more than a one-line summary (see goals/AGENTS.md) diff --git a/manifest b/manifest deleted file mode 100644 index 09cc46f9..00000000 --- a/manifest +++ /dev/null @@ -1,8 +0,0 @@ -C initial\sempty\scheck-in -D 2025-09-27T18:28:21.559 -R d41d8cd98f00b204e9800998ecf8427e -T *branch * trunk -T *sym-trunk * -U jnoble -Z 3f45351c1dc810e1e3525545cb4124cd -# Remove this line to create a well-formed Fossil manifest. diff --git a/manifest.tags b/manifest.tags deleted file mode 100644 index bec97179..00000000 --- a/manifest.tags +++ /dev/null @@ -1,2 +0,0 @@ -branch trunk -tag trunk diff --git a/manifest.uuid b/manifest.uuid deleted file mode 100644 index 49a7c4a2..00000000 --- a/manifest.uuid +++ /dev/null @@ -1 +0,0 @@ -8617f402ca78b8a1ae3566af83ccb97bec705e0b273c1ec5e76e8c6aa276a182