Skip to content

Build AI methods with your coding agent, then run them anywhere: as an MCP for chatbots, as a webapp for people, or via API for your software.

Answer the #1123 review threads: tighten the backup ignore glob and guard its cleanup

Louis Choquel03d95bca035e
diff --git a/.badges/tests.json b/.badges/tests.json
index c08c8d152..b580eb8a4 100644
--- a/.badges/tests.json
+++ b/.badges/tests.json
@@ -1,7 +1,7 @@
{
"schemaVersion": 1,
"label": "tests",
- "message": "10517",
+ "message": "10519",
"color": "blue",
"cacheSeconds": 300
}
\ No newline at end of file
diff --git a/.test_durations b/.test_durations
index 13bd8d5cd..743ac828b 100644
--- a/.test_durations
+++ b/.test_durations
@@ -6265,6 +6265,8 @@
"tests/unit/pipelex/migration/test_config_dir_gitignore.py::TestARealRunEnsuresIt::test_initializing_a_config_directory_writes_it": 1.1641,
"tests/unit/pipelex/migration/test_config_dir_gitignore.py::TestARealRunEnsuresIt::test_migrating_a_directory_leaves_the_rule_behind": 1.2049,
"tests/unit/pipelex/migration/test_config_dir_gitignore.py::TestBackupIgnorePattern::test_a_rescue_copy_stays_visible": 1.1969,
+ "tests/unit/pipelex/migration/test_config_dir_gitignore.py::TestBackupIgnorePattern::test_a_stamp_of_the_wrong_shape_is_not_one_of_ours": 0.5799,
+ "tests/unit/pipelex/migration/test_config_dir_gitignore.py::TestBackupIgnorePattern::test_a_user_named_copy_is_still_theirs_when_it_happens_to_start_with_a_digit": 0.5758,
"tests/unit/pipelex/migration/test_config_dir_gitignore.py::TestBackupIgnorePattern::test_it_does_not_hide_a_real_configuration_file": 1.1945,
"tests/unit/pipelex/migration/test_config_dir_gitignore.py::TestBackupIgnorePattern::test_it_leaves_a_copy_the_user_named_themselves_alone": 1.2,
"tests/unit/pipelex/migration/test_config_dir_gitignore.py::TestBackupIgnorePattern::test_it_matches_a_name_the_backup_module_actually_writes": 1.1902,
diff --git a/docs/migration-ledger.md b/docs/migration-ledger.md
index 2f4d442ca..615308c1c 100644
--- a/docs/migration-ledger.md
+++ b/docs/migration-ledger.md
@@ -673,7 +673,9 @@ Always back up, before writing. Exactly one backup per file — a successful run
The name is the source file's whole name, extension included, followed by `.bak.` and a compact UTC stamp: `pipelex.toml` backs up to `pipelex.toml.bak.20260815T120000Z`. Extension-included so a backup never shadows a real `.toml`, and separator-free so no filesystem objects to it. Pruning matches that whole shape, stamp included — a copy the user made by hand under a name that merely starts the same way (`pipelex.toml.bak.notes`) is theirs, and is never touched.
-**A backup does not belong in the user's `git status`, and pipelex writes the rule that keeps it out.** A project's `.pipelex/` is normally inside a git repository, so one run would otherwise put a dozen untracked `.bak.<stamp>` files in front of the user and leave them to work out which are ours. Pipelex therefore keeps a `.gitignore` *inside* the configuration directory, carrying one rule — `*.bak.[0-9]*Z`, built from the same infix and stamp shape the namer uses, so renaming either cannot leave a rule that matches nothing. In-directory rather than in the repository root because the walk is `~/.pipelex/` and the project `.pipelex/` and nothing else: every backup a migration can write inside a repository is already under a directory pipelex owns, which makes a local file a complete answer that needs no idea where the root is and never edits a file the user maintains for their whole project.
+**A backup does not belong in the user's `git status`, and pipelex writes the rule that keeps it out.** A project's `.pipelex/` is normally inside a git repository, so one run would otherwise put a dozen untracked `.bak.<stamp>` files in front of the user and leave them to work out which are ours. Pipelex therefore keeps a `.gitignore` *inside* the configuration directory, carrying one rule — `*.bak.` followed by the exact stamp shape, spelled out digit class by digit class, built from the same infix the namer uses so renaming it cannot leave a rule that matches nothing. The stamp is spelled out in full rather than abbreviated to a `[0-9]*` run, because a run would also swallow a copy the user named themselves along the lines of `pipelex.toml.bak.1-notesZ` — one pruning explicitly refuses to touch, and hiding a file we decline to manage is the worse half of both answers. In-directory rather than in the repository root because the walk is `~/.pipelex/` and the project `.pipelex/` and nothing else, so a local file needs no idea where the root is and never edits a file the user maintains for their whole project.
+
+One backup is deliberately out of reach of this rule. A configuration file that is a symlink is migrated through to the file it names, so its backup lands beside *that* file — in a dotfiles directory, which is the user's and not ours. Pipelex does not follow it there: writing into the `.gitignore` of somebody's whole dotfiles repository is a larger liberty than the single untracked copy it would hide.
The file is written by `pipelex init`, and by any real (non-`--dry-run`) `pipelex migrate` — the second so that a machine whose `.pipelex/` predates this gets the rule from the very run that would otherwise dirty it. It is **create-if-absent and nothing more**: once a `.gitignore` is there it is a file in the user's repository, possibly theirs, possibly ours with a line taken out on purpose, and re-asserting a rule into it every run would be a tool arguing with its user. Two omissions are deliberate. A `.rescue.` copy is **not** ignored — it exists only because a write could not be vouched for and the report tells the user to go and get it, so turning up in `git status` is that reminder working. Neither is a copy the user named themselves: pruning already refuses to touch a `pipelex.toml.bak.notes` on the grounds that it is theirs, and hiding it from their own `git status` would be the same mistake pointed the other way.
diff --git a/pipelex/migration/gitignore.py b/pipelex/migration/gitignore.py
index f4e03cb19..0587434c8 100644
--- a/pipelex/migration/gitignore.py
+++ b/pipelex/migration/gitignore.py
@@ -8,11 +8,16 @@ them writes a slightly different one, or forgets, and a tool that dirties a repo
it runs stops getting run.
**Why the rule lives here and not in the user's root `.gitignore`.** The walk is the global
-`~/.pipelex/` and the project `.pipelex/`, and nothing else (see `run.py`), so every backup a
-migration can ever write inside a repository is under a directory pipelex already owns. That makes
-a `.gitignore` *in* that directory a complete answer — it needs no knowledge of where the
-repository root is, survives the directory being moved or vendored, and never reaches into a file
-the user maintains for their whole project.
+`~/.pipelex/` and the project `.pipelex/`, and nothing else (see `run.py`), so a backup written
+under a directory pipelex already owns is answered by a `.gitignore` *in* that directory — one that
+needs no knowledge of where the repository root is, survives the directory being moved or vendored,
+and never reaches into a file the user maintains for their whole project.
+
+**The one backup this does not reach, and why it is left.** A configuration file that is a symlink
+is migrated through to the file it names, and its backup lands beside *that* file (see
+`runner.migrate_file`) — in a dotfiles directory, which is the user's and not ours. The rule
+deliberately does not follow it there: writing into the `.gitignore` of somebody's whole dotfiles
+repository is a larger liberty than the one untracked copy it would hide.
**The pattern is derived from the namer, not retyped.** `BACKUP_INFIX` is what
`backup_path_for` actually writes; spelling `*.bak.…` again here would let a rename of the infix
@@ -38,11 +43,25 @@ from pipelex.migration.backup import BACKUP_INFIX
CONFIG_DIR_GITIGNORE_NAME = ".gitignore"
"""What the file is called inside `~/.pipelex/` or a project's `.pipelex/`."""
-BACKUP_IGNORE_PATTERN = f"*{BACKUP_INFIX}[0-9]*Z"
-"""The one rule the file carries: any name ending in the infix, a digit-led run, and the UTC `Z`.
+_STAMP_GLOB = f"{'[0-9]' * 8}T{'[0-9]' * 6}Z"
+"""The shape `BACKUP_STAMP_FORMAT` renders, written in the only vocabulary a `.gitignore` has.
+
+A glob has no repetition count, so the eight-digit date and the six-digit time are spelled out
+rather than abbreviated to a `[0-9]*` run. The run looks equivalent and is not: its `*` accepts
+anything at all, so it also matches `pipelex.toml.bak.1-notesZ` — a name `existing_backups_of`
+reads as the user's own and refuses to prune. Hiding a file we have just declined to manage is the
+worse half of both answers.
+
+Nothing translates the strftime string into this, on purpose: a parser for format directives is
+more machinery than one constant is worth. What holds the two together is the test matching this
+pattern against a name `backup_path_for` actually produced, which goes red if the stamp restamps.
+"""
+
+BACKUP_IGNORE_PATTERN = f"*{BACKUP_INFIX}{_STAMP_GLOB}"
+"""The one rule the file carries: any name ending in the infix followed by exactly the stamp.
-The digit and the trailing `Z` are what `BACKUP_STAMP_FORMAT` renders and what a name the user
-chose does not, which is how `pipelex.toml.bak.notes` stays visible.
+Exactly the stamp, rather than something stamp-shaped, is what keeps `pipelex.toml.bak.notes` — and
+every other copy the user named themselves — visible in their own `git status`.
"""
_GITIGNORE_CONTENT = f"""\
@@ -90,6 +109,13 @@ def ensure_config_dir_gitignore(*, directory: Path) -> bool:
handle.flush()
os.fsync(handle.fileno())
except OSError:
- path.unlink(missing_ok=True)
+ try:
+ path.unlink(missing_ok=True)
+ except OSError:
+ # `missing_ok` covers a file that is gone, not a filesystem that says no — and the one
+ # that just refused the write is exactly the one that can refuse the removal. Letting
+ # that escape would turn a missing convenience rule into a failed migration, which is
+ # the outcome every other branch of this function exists to avoid.
+ pass
return False
return True
diff --git a/tests/unit/pipelex/migration/test_config_dir_gitignore.py b/tests/unit/pipelex/migration/test_config_dir_gitignore.py
index b8c983d60..405727245 100644
--- a/tests/unit/pipelex/migration/test_config_dir_gitignore.py
+++ b/tests/unit/pipelex/migration/test_config_dir_gitignore.py
@@ -38,6 +38,20 @@ class TestBackupIgnorePattern:
"""`existing_backups_of` refuses to prune one of these; the ignore rule must not hide it."""
assert not fnmatch("pipelex.toml.bak.notes", BACKUP_IGNORE_PATTERN)
+ def test_a_user_named_copy_is_still_theirs_when_it_happens_to_start_with_a_digit(self) -> None:
+ """The near-miss the rule has to survive, since a user name is not required to avoid our shape.
+
+ Pruning reads each of these as the user's file and leaves it standing. A rule loose enough
+ to hide one would take the file out of the `git status` it is then never going to manage.
+ """
+ for name in ("pipelex.toml.bak.1-notesZ", "pipelex.toml.bak.2026notesZ", "pipelex.toml.bak.0Z"):
+ assert not fnmatch(name, BACKUP_IGNORE_PATTERN), name
+
+ def test_a_stamp_of_the_wrong_shape_is_not_one_of_ours(self) -> None:
+ """The whole stamp is the evidence, so a name carrying only part of it is somebody else's."""
+ for name in ("pipelex.toml.bak.2026T121441Z", "pipelex.toml.bak.20260818T1214410Z", "pipelex.toml.bak.20260818121441Z"):
+ assert not fnmatch(name, BACKUP_IGNORE_PATTERN), name
+
def test_a_rescue_copy_stays_visible(self, tmp_path: Path) -> None:
"""It is the one file the report tells the user to go and get — hiding it defeats the point."""
rescue = rescue_path_for(path=tmp_path / "pipelex.toml", moment=MOMENT)
@@ -57,7 +71,11 @@ class TestEnsureConfigDirGitignore:
assert (tmp_path / CONFIG_DIR_GITIGNORE_NAME).read_text().splitlines()[-1] == BACKUP_IGNORE_PATTERN
def test_the_file_it_writes_actually_ignores_a_backup(self, tmp_path: Path) -> None:
- """The end the whole change exists for, asserted against git itself rather than by eye."""
+ """The end the whole change exists for: a real backup name, matched against the file's own rules.
+
+ Read out of the written file and matched line by line, rather than against the constant, so
+ a rule that never reached the file — or reached it commented out — is caught here.
+ """
ensure_config_dir_gitignore(directory=tmp_path)
written = (tmp_path / CONFIG_DIR_GITIGNORE_NAME).read_text()
diff --git a/wip/pr-1123-review-notes.md b/wip/pr-1123-review-notes.md
new file mode 100644
index 000000000..45f5284e7
--- /dev/null
+++ b/wip/pr-1123-review-notes.md
@@ -0,0 +1,35 @@
+# PR #1123 review follow-up — the one backup the config-directory `.gitignore` cannot reach
+
+**Status:** Deferred from the v0.46.2 release review (2026-08-18). Not a regression — the gap arrives with the feature, and the feature is still a strict improvement over having no rule at all. What is deferred is the *remedy*, because every version of it is a design reversal rather than a fix.
+
+**Reported by:** Codex (thread `PRRT_kwDOOwmMFc6aHHck`) and cubic (thread `PRRT_kwDOOwmMFc6aHLr8`), both against `pipelex/migration/run.py:69-71`. Both threads were left open on purpose.
+
+## What is true
+
+`migrate_config_directories` ensures a `.gitignore` in each *walked* configuration directory — `~/.pipelex/` and the project `.pipelex/`. But `migrate_file` resolves symlinks before it snapshots the file (`pipelex/migration/runner.py:42`, `read_file_snapshot(file_path.resolve())`), deliberately and with a comment saying so: an atomic replace of the link path would delete the link and leave the real file unmigrated. The backup is then named from the *resolved* path, so for a dotfiles setup — `.pipelex/pipelex.toml` symlinked to `~/dotfiles/pipelex.toml` — the `.bak.<stamp>` copy lands in `~/dotfiles/`, which the rule in `.pipelex/` cannot match. If that directory is itself a git repository, migrating dirties it, which is the exact workflow the feature exists to fix.
+
+The behavior is covered by an existing test (`tests/unit/pipelex/migration/test_runner.py:602`), so this is a known, intended resolution — not an accident.
+
+## Why nothing was changed
+
+Two remedies present themselves, and both cost more than the gap:
+
+- **Ensure a `.gitignore` beside the resolved backup too.** That means creating or relying on a `.gitignore` at the root of the user's dotfiles repository — a file they maintain for their whole project, which the design of this feature explicitly refuses to touch (`pipelex/migration/gitignore.py`, "never reaches into a file the user maintains for their whole project"). Writing there to hide one transient copy is a much larger liberty than the copy is worth.
+- **Write the backup beside the link instead of the target.** That reverses a documented and tested decision about where a copy of a file belongs, and it would put the backup in a directory that is not the one holding the file it copies.
+
+A third possibility exists and is the reason this is written down rather than closed: **do neither, and instead not back up through a symlink at all when the target is outside the walked directory** — reporting the file as one the migration will not rewrite on its own. That is a real behavior change with a real cost (a dotfiles user loses in-place migration), so it is a call for a human, not for a review pass on a release branch.
+
+## What was done instead
+
+The overclaim was removed. Both `pipelex/migration/gitignore.py`'s module docstring and `docs/migration-ledger.md` asserted that *every* backup a migration can write inside a repository is under a directory pipelex owns. That sentence is false under a symlink, and it is now replaced by an explicit statement of the exception and why the rule does not follow it.
+
+## The open question
+
+For a user whose `.pipelex/` configuration files are symlinks into a git-tracked dotfiles directory, should `pipelex migrate`:
+
+1. keep today's behavior and accept that the backup dirties the target's repository (with the docs saying so, which is the current state);
+2. leave the backup beside the link rather than the target;
+3. decline to migrate through a symlink whose target is outside the walked directory, and report the file as one the user must handle; or
+4. something else — e.g. name the escaped backup path in the migration report, so the user is told where the copy went rather than finding it in `git status`?
+
+Option 4 is the cheapest and is worth considering on its own even if the answer to 1–3 is "keep today's behavior": the report already names paths, and a user who is told is not a user who is surprised.