Ignore the output directories, not just their extensions

[michakraus]

Run output was covered by extension patterns only (*.h5, *.hdf5, *.pdf, *.png). Extension patterns leave whatever else a run drops behind untracked but visible, and they do not stop a driver from being written into an output directory — so the output directories are now ignored as directories.

figures/ is the one that matters here. It is the default plot directory — PLOT_DIR in src/common.jl, created by mkpath in common.jl, guiding-center-4d-poincare.jl, standard-map.jl and convergence.jl — and it was covered by *.png alone, so the directory itself and any non-matching artefact in it stayed visible. Weaving creates it under the already-ignored docs/src/<problem>/, but calling a run driver from the repository root creates it at the root. It is ignored at any depth; the trailing slash keeps a plain file of that name trackable.

/runs and /results are root-anchored and come along for the run-data-and-rendered-output split, which the drivers in this repository do not use yet — there is no such directory on disk and no code path that creates one. They are forward-looking, not a fix to anything currently broken.

The extension patterns stay, since examples write figures outside these directories too.

Nothing was tracked under any of the three, so the change cannot untrack anything and no history is affected: git ls-files is empty for all three, git ls-tree -r on the base likewise, and git ls-files -i -c --exclude-standard returns nothing after the change.

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

The changelog entry references Packages/CLAUDE.md, but that file does not exist in this repository, making the documentation misleading.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR updates the repository ignore rules so example run output directories are ignored directly (not only by file extension patterns), and documents the change in the changelog.

Changes:

• Add root-anchored ignore entries for /runs and /results in .gitignore while keeping existing extension-based patterns.
• Add a corresponding note to the Unreleased “Changed” section in CHANGELOG.md.

File summaries

File	Description
.gitignore	Adds root-anchored ignore rules for run/output directories.
CHANGELOG.md	Documents the .gitignore change in the Unreleased section.

Review details

• Files reviewed: 1/2 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[michakraus]

Review — changes requested

The rule is real and it does govern this repository (Experiments/CLAUDE.md inherits
Packages/CLAUDE.md, whose scripts/, runs/, results/ section requires exactly these two
root-anchored patterns), and the untracking claim in the description checks out: git ls-files -- runs results is empty on the branch and git ls-tree -r origin/main has no path under either. Two
findings, one substantive.

1. The gap this closes is not the gap this repository has

/runs and /results are inert here. Neither directory exists on disk, and no code path in the
repository can create one — there is no scripts//runs//results/ layout at all. Every output
directory comes from plot_dir, which defaults to

src/common.jl:19    const PLOT_DIR = "figures"

and is created by mkpath at src/common.jl:325, src/guiding-center-4d-poincare.jl:205,
src/standard-map.jl:141 and src/convergence.jl:69. A grep for a runs/results path literal
or a --runs-dir/--results-dir option over *.jl, *.jmd, Makefile, *.yml returns nothing.

So the directory the rule's own reasoning applies to in this repository is figures, and it stays
uncovered after this change:

$ git check-ignore -v figures/ figures/foo.jld2 figures/x.png
.gitignore:17:*.png    figures/x.png

— the directory and a non-matching artefact in it are not ignored; only the .png is, by extension.
That is precisely the sentence the changelog entry quotes: "they do not stop a driver from being
written into an output directory."

Today this is latent rather than live, and worth saying so: every figures/ on disk sits under
docs/src/<problem>/ or docs/build/, both already ignored by directory, because the documented
entry points all run from docs/ and test/test_scripts.jl works in a temporary directory. But
run_list(...) called from the repository root — the obvious interactive use — does mkpath on
./figures at the root, untracked and visible, with any non-.png artefact in it unignored.

Please add figures/ (unanchored, so it catches it at any depth) alongside the two new patterns.
Nothing tracked would be shadowed: git ls-files | grep -i figures is empty. Alternatively, if the
intent is forward-looking conformance for a layout this repository does not yet have, that is fine —
but then the changelog should say so, because as written it asserts it is closing a live gap in this
repository's output handling, and the live one is figures.

2. The changelog cites a file no reader of this repository can reach (upholding Copilot's point)

CHANGELOG.md:15 points at Packages/CLAUDE.md. This is a public repository; that file is not in
it and is not published anywhere — it exists only in the author's local research tree. It is also
the only CLAUDE.md reference in the whole changelog, so it is a new leak of a private convention
rather than an established house style. The reasoning in the entry stands perfectly well on its own;
drop the citation and state the reason directly (root-anchored directory ignores over extension
patterns, and why).

Not blocking

• Placement under [Unreleased] → Changed, ordering ahead of the solver-stack entry, and the
  comment rewording (# Run data and rendered output…, # Solution and figure files, wherever an example writes them) are all right, and the second comment is a genuine improvement on the
  original — it now says why the extension patterns are still there.
• The two added patterns are harmless as they stand; finding 1 is that they are insufficient, not
  that they are wrong.

CI

Not green yet at time of review: Doctests - ubuntu-latest passes; the nine Julia jobs
(1/min/pre/nightly × ubuntu/macOS/windows) are all still pending on run 34109769706. A .gitignore
and CHANGELOG.md diff has no executable line in it, so a red job would be unrelated to this
branch — but the matrix should be read before merging regardless.

[michakraus]

Both review findings are addressed in ff5a029.

1. figures/ is now ignored. It is the output directory this repository actually creates (PLOT_DIR in src/common.jl:19), and it was covered by *.png alone. Unanchored with a trailing slash, so it catches the directory at any depth while leaving a plain file of that name trackable:

$ git check-ignore -v figures/ figures/foo.jld2 figures/x.png
.gitignore:14:figures/   figures/
.gitignore:14:figures/   figures/foo.jld2
.gitignore:14:figures/   figures/x.png
$ git check-ignore -v figures        # a plain file — correctly not ignored
$ git ls-files -i -c --exclude-standard   # nothing tracked is shadowed

/runs and /results are kept, and the changelog and the PR description now say plainly that they are ahead of the drivers rather than closing a live gap.

2. The Packages/CLAUDE.md citation is gone from both the changelog and the PR description — @copilot-pull-request-reviewer was right that it points at a file no reader of this repository can reach. The entry states the reason directly instead.

.gitignore and CHANGELOG.md are the only files touched, so there is no executable line in the diff and no Julia-side check to re-run; the matrix should still be read before merging.

[michakraus]

Review — verdict: approve

Second reviewing session, reading ff5a029 fresh. .gitignore and CHANGELOG.md are the only
files touched (+17 / −1), so there is no executable line in this diff. Every factual claim in the
description and the changelog entry checks out against the tree:

claim	check	result
figures is the default plot directory	src/common.jl:19 — const PLOT_DIR = "figures"	confirmed
run drivers mkpath it	common.jl:325, guiding-center-4d-poincare.jl:205, standard-map.jl:141, convergence.jl:69	confirmed, all four
ignored at any depth	git check-ignore -v matches figures/, figures/foo.jld2, docs/src/a/figures/x.dat — all .gitignore:14	confirmed
a plain file figures stays trackable	git check-ignore figures → exit 1	confirmed
/runs, /results root-anchored	match runs/a.h5, results/b.txt; neither exists on disk	confirmed
nothing tracked is shadowed	git ls-files empty for all three; git ls-files -i -c --exclude-standard empty; no tracked .png/.pdf/.h5/.hdf5/.jld2 anywhere	confirmed
the private-path citation is gone	grep -n CLAUDE CHANGELOG.md → no match	confirmed

Two points beyond re-verifying the previous round:

• figures/ is redundant against the weave output but not pointlessly so. The fifteen
  docs/src/<problem>/ directories are already ignored wholesale further down the file, so the new
  pattern changes nothing there. What it actually covers is the root-level ./figures that
  run_list creates when a driver is called from the repository root — which is exactly what the
  changelog says it covers. The overlap is not a defect.
• This is the only .gitignore in the repository, so there is no nested file whose negation
  could interact with an unanchored pattern. Worth stating because unanchored directory ignores are
  the kind that surprise later.

The /runs and /results pair remains forward-looking, and both the changelog and the description
now say so plainly rather than implying a live gap — which was finding 1 of the previous round.
Keeping them is a judgement call I would make the same way: they cost nothing and they document the
intended layout.

CI

Read before merging: all nine jobs green on run 34111352370 — Doctests, plus Julia
1/min/pre/nightly across ubuntu, macOS and windows.

No outstanding requested changes: both existing reviews are COMMENTED
(copilot-pull-request-reviewer, michakraus).

Merging.