From 7c8d9c955ac0db5458fda04dc58b1bb313f5182c Mon Sep 17 00:00:00 2001 From: Jeppe Lillevang Salling Date: Sat, 18 Jul 2026 01:09:42 +0200 Subject: [PATCH] docs: reconcile --gitignore-global wording with shipped --visibility Closes #65. The canonical instructions (.agent/AGENTS.md, symlinked as AGENTS.md / CLAUDE.md / .agent/CLAUDE.md) still described machine-wide git excludes as a *planned, not-yet-exposed* `--gitignore-global` flag. That capability shipped as `agent-init init --visibility=global-default` (#52/#61, plus the hidden/local modes in #70), so the doc contradicted the binary and risked someone re-implementing it under the old flag name. - Add `--visibility` and `--private` rows to the "Flags on init" table. - Replace the "Planned `--gitignore-global`" section with "Visibility and global excludes", describing the shipped modes and noting global-default is the superseding form. Machine-wide footgun warning preserved. - Update the kebab-case flag example and the global-git-config guardrail to reference `--visibility=global-default`. - Reframe the "Global gitignore is a footgun" note as shipped, keeping the warning. README.md and docs/cli.md already document --visibility (incl. global-default) with no stale `--gitignore-global` mentions; verified, no change needed there. Co-Authored-By: Claude Opus 4.8 (1M context) --- .agent/AGENTS.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/.agent/AGENTS.md b/.agent/AGENTS.md index 6bd0c2d..35d67f9 100644 --- a/.agent/AGENTS.md +++ b/.agent/AGENTS.md @@ -79,10 +79,12 @@ Releases are tag-driven. Pushing a semver tag (`vX.Y.Z`) is the only trigger tha | `--force` | Overwrite existing files. Default: skip with a notice. | | `--no-git` | Skip `git init` if target isn't already a repo. | | `--dry-run` | Print what would happen without writing anything. | +| `--visibility` | How the scaffold is tracked by git: `shared` (default, committed), `local` (ignored via a committed `.gitignore` block), `hidden` (ignored via `.git/info/exclude`, no committed trace), or `global-default` (ignored via the machine-wide git excludes file — affects every repo). Code flavors only. | +| `--private` | Alias for `--visibility=hidden`. | -### Planned `--gitignore-global` +### Visibility and global excludes -Global gitignore support is planned but not exposed until implemented. When added, it must be idempotent, use a clearly marked managed block, include tests in `internal/gitconfig/`, and warn that global excludes affect every repository on the user's machine. +All four `--visibility` modes are implemented; see [`docs/cli.md`](../docs/cli.md) and the handlers in `internal/cli` (managed-block content in `internal/gitignore`, global-excludes resolution in `internal/gitconfig`). `--visibility=global-default` is the shipped form of what earlier docs described as a planned `--gitignore-global` flag: it writes a clearly-marked, idempotent managed block to the user's machine-wide git excludes file. That reach is a footgun — it ignores the scaffold in *every* repository on the machine — so it is never the default, prints a loud warning plus the absolute path it edited, and is reversible by removing the block. Covered by tests in `internal/gitconfig/` and `internal/gitignore/`. ## Conventions @@ -120,7 +122,7 @@ Templates are embedded via `//go:embed all:templates`. Important constraints: - Files: snake_case for Go files (`flavor_registry.go`), kebab-case for shell scripts (`gen-codemap.sh`), as conventions dictate. - Exported Go identifiers: idiomatic CamelCase, no stutter (`flavors.Registry` not `flavors.FlavorRegistry`). -- CLI flags: kebab-case (`--no-git`, `--force`, `--gitignore-global`). +- CLI flags: kebab-case (`--no-git`, `--dry-run`, `--visibility`). ### Commits @@ -205,7 +207,7 @@ The per-flavor hooks (`Symlinks`, `NextSteps`, optional `CommonTemplates`) are d - Do not bypass `check.sh` failures with `--no-verify` or by editing the script. - Do not introduce a templating engine other than `text/template` (or `html/template` for HTML files, if that ever applies). The `.tmpl` extension convention exists specifically to avoid escaping wars with files that contain `{{` natively. - Do not add a flavor without a golden-file test. Untested templates rot. -- Do not modify the user's global git config without it being an explicit user-requested action (i.e. only the `--gitignore-global` flag may touch it, and only with the documented managed-block pattern). Never silently mutate any other `git config --global` keys. +- Do not modify the user's global git config without it being an explicit user-requested action (i.e. only `--visibility=global-default` may touch it, and only with the documented managed-block pattern). Never silently mutate any other `git config --global` keys. ## When you're stuck @@ -240,4 +242,4 @@ If you find yourself doing repetitive work that neither skill covers, propose a - **Recursion gotcha:** this repo's own `.agent/`, `.devcontainer/`, `Justfile`, etc. are local working files for developing `agent-init`. They are not authoritative downstream templates — those live under `internal/flavors/*/templates/`. When you're tempted to "fix" this repo's top-level scaffolding, ask whether the fix belongs in a flavor template instead. - **IaC flavors (phase 2) will need different defaults**, especially: no Playwright, codemap based on Terraform modules / Ansible roles, different mount conventions in the devcontainer (state files, SSH keys for Ansible — handle carefully and document the security implications in the flavor's own README). - **The binary must be cross-compilable.** `GOOS=linux GOARCH=amd64 go build` and `GOOS=darwin GOARCH=arm64 go build` both have to work. Don't reach for syscalls or platform-specific paths without a build tag. -- **Global gitignore is a footgun.** Do not expose `--gitignore-global` until it is implemented and tested. When implementing it, the help text and any printed output must make clear that the change is machine-wide and affects every repo. Default is `off` for this reason. Don't be clever about defaults. +- **Global gitignore is a footgun.** It ships as `--visibility=global-default`, not a separate `--gitignore-global` flag. The help text and printed output make clear the change is machine-wide and affects every repo, and it is never the default — keep it that way. Don't be clever about defaults.