docs(recipe): directory links pin the gate to >=0.8.0#21
Merged
Conversation
The elevating-your-link-gate recipe is the public reference, and it didn't mention directory links (0.8.0). Two additions: §1 notes the gap now includes plain links to folders-with-README; §6 adds the critical version coupling — an older darnlink treats a robust directory link as broken and repairs it into README.md, so the gate binary must be >=0.8.0 before you robustify the first one. Also points to --create-readme for README-less folders. Docs only.
There was a problem hiding this comment.
Pull request overview
Updates the elevating-your-link-gate recipe to explicitly cover directory links (folders with README.md) and to document the minimum darnlink version coupling required to avoid older gates rewriting directory links into README.md file links.
Changes:
- Adds a §1 note that the “gap” (plain links flagged by
--robustify) now includes directory links since 0.8.0. - Adds a §6 warning explaining why gates must run a dir-link-aware darnlink version (≥ 0.8.0) before directory links are robustified, and points to
--create-readmefor README-less folders.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+211
to
+213
| > rewrites it to `foo/README.md` (the file), silently destroying the folder link. **Pin your gate to | ||
| > `darnlink==0.8.0` (or later) before you robustify the first directory link** — bumping an already-live | ||
| > gate from an older pin, and robustifying the directory links, is one atomic step. A folder with no |
Owner
Author
There was a problem hiding this comment.
Valid — fixed in 9012ec0: now reads 'require darnlink >= 0.8.0 (pin a concrete 0.8.0-or-newer release)', so the minimum-version requirement isn't phrased as an exact pin.
…on (Copilot #21) 'darnlink==0.8.0 (or later)' mixed an exact pin with a minimum. State it as 'require darnlink >= 0.8.0 (pin a concrete 0.8.0-or-newer release)'.
| > (anchored to its `README.md`'s uuid — [FORMAT.md §4.1](../FORMAT.md#41-directory-links) <!-- uuid: 9052d864-2a45-4ed4-8725-d8a394e7a7ef -->). Two consequences for the wall: | ||
| > **(1)** `--robustify` now flags plain **directory** links too, so they are part of the gap you close | ||
| > above; **(2)** the gate binary **itself** must be ≥ 0.8.0 — an older `darnlink` doesn't understand a | ||
| > directory link, so its `repair` pass treats a robust `[x](foo/) <!-- uuid -->` as *broken* and |
Owner
Author
|
Verdict: ready to merge. Docs-only; Copilot's phrasing finding (minimum-version vs exact pin) fixed; re-review clean, CI green. Merging — the public recipe now covers directory links and the ≥0.8.0 gate coupling. |
txemi
added a commit
that referenced
this pull request
Jul 23, 2026
…(spec 014) Bumps 0.9.1 → 0.10.0 (one minor per feature/spec, as with 011/012/013). Feature 014: --create-readme no longer writes a README into a folder holding a darnlink-ignore-file'd (downloaded) file — the provenance-based, surgical alternative to excluding a whole mirror. Also the recipe now documents directory links + the >=0.8.0 gate coupling (#21).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
The elevating-your-link-gate recipe is the public reference everyone follows, and it didn't
mention directory links (feature 011, 0.8.0) at all. Two focused additions:
has a
README.md; they robustify/heal like file links.darnlinkdoesn't understand adirectory link, so its
repairpass treats a robust[x](foo/) <!-- uuid -->as broken andrewrites it to
foo/README.md, silently destroying the folder link. So the gate binary itselfmust be ≥ 0.8.0 — bump the pin and robustify the directory links as one atomic step. Also points
to
--create-readmefor README-less folders.Why
This is a real gotcha lived in the field: bumping a live gate from 0.6.0 to a dir-link-aware version is
not optional once directory links exist — a stale gate mangles them. The reference should say so.
Docs only. Scoped to two note blocks to minimise conflict with the in-flight web-layer edits to the
same file. The
--create-readme"skips downloaded/external folders" refinement will be added once thatPR lands.