git-rhizoid

Design log and progress for Rhizoid - decisions, concepts, and backlog, kept the tad way.

Concepts

Rhizoid-cutting (rhizcut)

Summary
A single dependency managed by Rhizoid: a real GitHub fork of an upstream repo, owned and pinned rather than referenced remotely. Named after a horticultural cutting - a piece taken from a parent plant and rooted separately, genetically identical at the start but independent from then on.
Tags
naming
Relations
← concerns: Additive-only file structure — the property that makes a rhizoid-cutting update conflict-free
← concerns: Adopt an existing fork vs create a new one — both add and import produce a rhizoid-cutting; they differ in whether a new fork is created
Sources
Go Modules Reference, git-vendor (thejoshwolfe)

Additive-only file structure

Summary
Rhizoid-managed metadata (manifest, sync state) is added as new files alongside upstream’s own, never edited in place inside upstream’s existing files. This keeps a pull from upstream conflict-free for the tracked branch - not a guarantee that any patch to upstream code stays conflict-free, only that Rhizoid’s own bookkeeping never collides with it.
Tags
design
Relations
→ concerns: Rhizoid-cutting (rhizcut) — the property that makes a rhizoid-cutting update conflict-free
← pairs-with: Tracking branch vs patch branch — together they define what “conflict-free” actually means here
← concerns: Status detects drift, not just reports the manifest — drift detection is what notices when the additive structure itself has been touched or is missing
Sources
wei/pull, Sync a fork - REST API

Tracking branch vs patch branch

Summary
The branch that mirrors upstream is never hand-edited - only fast-forwarded via merge-upstream. All customization lives on a separate branch that merges from the tracking branch. The tracking branch never conflicts; the patch branch might, exactly once, when upstream touches a line you also patched - that is inherent to patching, not a tooling failure.
Tags
design
Relations
→ pairs-with: Additive-only file structure — together they define what “conflict-free” actually means here
← concerns: Clean patch back upstream — a clean patch is only possible because the tracking branch stays pristine

Clean patch back upstream

Summary
Because Rhizoid’s own metadata never touches upstream’s files, a diff of the patch branch against the pristine tracking branch is a clean patch, submittable as a normal PR to the original repo, whether or not its owner has ever heard of Rhizoid.
Tags
design
Relations
→ concerns: Tracking branch vs patch branch — a clean patch is only possible because the tracking branch stays pristine
Sources
To Fork or Not to Fork

Status detects drift, not just reports the manifest

Summary
rhizoid status inspects the real state of every managed fork (does it exist, what commit is the tracking branch actually at, is there uncommitted or unmanifested structure) and diffs that against the manifest’s record, the way terraform plan diffs real infrastructure against Terraform state. The manifest is a record of intent, not a source of truth Rhizoid trusts blindly - reality always wins the comparison.
Tags
design
Relations
→ concerns: Additive-only file structure — drift detection is what notices when the additive structure itself has been touched or is missing
← pairs-with: No central lockfile - state is distributed into each fork — status/refresh read the distributed state directly instead of a lockfile
Sources
Manage Resource Drift

Adopt an existing fork vs create a new one

Summary
Two different, deliberately separate operations: rhizoid add forks a new copy of upstream; rhizoid import points at a fork that already exists (with or without the rhizoid wrapper already on it) and adopts it into the manifest without creating anything. Kept as two verbs rather than one flag with a default, the way terraform keeps import separate from apply - the two operations have different blast radii and a wrong default in either direction is a real mistake (an unwanted duplicate fork, or silently overwriting someone’s existing, satisfactory fork).
Tags
design
Relations
→ concerns: Rhizoid-cutting (rhizcut) — both add and import produce a rhizoid-cutting; they differ in whether a new fork is created
← concerns: The v1 command surface: init, add, import, update, status, refresh, remove — add and import are two of its seven verbs
Sources
Manage Resource Drift

Fork destination is a manifest setting, not hardcoded

Summary
Where a new fork lands (which org or account) is configured per manifest, with a default and a per-module override - the same shape as west’s remotes list (a named set of url-bases) plus each project’s optional remote: override. Nothing about Rhizoid assumes forks live in one specific org.
Tags
design
Relations
← concerns: The v1 command surface: init, add, import, update, status, refresh, remove — add reads the destination org from here
Sources
West Manifests

The v1 command surface: init, add, import, update, status, refresh, remove

Summary
init sets up a manifest. add forks a new module into the configured org and starts tracking it. import adopts an existing fork without creating one. update pulls upstream into a module’s tracking branch (GitHub’s merge-upstream). status reports drift between the manifest and real git/GitHub state. refresh reconciles the manifest to match observed reality without changing anything (mirrors terraform apply -refresh-only) - this is how a by-hand change gets folded back in rather than flagged as drift forever. remove drops a module from the manifest. send-upstream (clean patch back to the true upstream) is real but deferred to v0.2, after the core loop is proven.
Tags
design
Relations
→ concerns: Each fork carries its own .rhizoid/module.toml — status/refresh/update all read and write this file
→ concerns: Fork destination is a manifest setting, not hardcoded — add reads the destination org from here
→ concerns: Adopt an existing fork vs create a new one — add and import are two of its seven verbs

Each fork carries its own .rhizoid/module.toml

Summary
The additive metadata that makes a fork “attached” lives in a new .rhizoid/module.toml file at the fork’s own root: origin URL, tracked ref, pinned commit, whether it was added or imported, when. Mirrors .tad/.gitrepo’s pattern from the tad system - a plain, readable file is the source of truth for state, not something buried in commit messages or a separate database.
Tags
design
Relations
← concerns: The v1 command surface: init, add, import, update, status, refresh, remove — status/refresh/update all read and write this file
← pairs-with: The manifest is TOML, with the footgun that argues against it named up front — the top-level manifest and each fork’s own metadata file are both TOML, for the same reasons
← concerns: No central lockfile - state is distributed into each fork — this is what makes a central lockfile unnecessary
← pairs-with: Two crates: rhizoid-core and rhizoid-cli — rhizoid-core owns both the top-level manifest type and the per-fork metadata type

The manifest is TOML, with the footgun that argues against it named up front

Summary
TOML: native comments (unlike JSON), no implicit type coercion or indentation sensitivity (unlike YAML - see the YAML document from hell), and its array-of-tables syntax is a direct fit for “a list of modules, each a flat record”. Cross-ecosystem adoption for exactly this kind of file (a hand-editable project/tool manifest, not a deeply-nested orchestration config) is real and independent of any one language: Cargo.toml, pyproject.toml, Hugo, Netlify. The honest counter-case: Cloudflare’s Wrangler shipped TOML-only for years, then added JSONC and now recommends it for new projects, naming TOML’s array-of-tables syntax as a real footgun in practice - a misplaced or missing [[table]] header silently puts a value in the wrong entry (see the future of Wrangler configuration). That risk is highest when a file is mostly hand-typed from scratch, which is not the common case here: the manifest is meant to be edited through add/import/remove, not freehand, and each module’s own detailed state lives in its own .rhizoid/module.toml rather than piling many [[module]] entries into one large hand-edited file - closer to Cargo.toml’s [dependencies] table (mostly tool-written) than to a large hand-maintained Wrangler config.
Tags
design
Relations
→ pairs-with: Each fork carries its own .rhizoid/module.toml — the top-level manifest and each fork’s own metadata file are both TOML, for the same reasons
← pairs-with: Two crates: rhizoid-core and rhizoid-cli — rhizoid-core is where the TOML/schema decision actually gets implemented
Sources
TOML: Tom’s Obvious, Minimal Language, The YAML Document From Hell, The future of Wrangler configuration

No central lockfile - state is distributed into each fork

Summary
Cargo, npm, Poetry and Nix all pair a human-edited manifest with a separate, machine-written lockfile recording exact resolved state. Rhizoid does not need a top-level lockfile: each managed fork is already a real git repository with its own history, and its own .rhizoid/module.toml already carries that module’s exact recorded state (see module-metadata-file). A central lockfile would just be a second, independently-driftable copy of information git already holds per-repo.
Tags
design
Relations
→ concerns: Each fork carries its own .rhizoid/module.toml — this is what makes a central lockfile unnecessary
→ pairs-with: Status detects drift, not just reports the manifest — status/refresh read the distributed state directly instead of a lockfile

Auth: shell out to gh, for now

Summary
Rhizoid calls the GitHub CLI (gh) for anything needing authentication - forking, merge-upstream, reading repo state - rather than managing its own token or OAuth flow. Whoever already has gh authenticated can use Rhizoid immediately; the tool has no credentials of its own to store, rotate, or leak. Revisit if a use case needs something gh cannot do (a non-GitHub git host, for one).
Tags
design

argenv declares flags and env vars - not subcommands or positionals

Summary
Read argenv’s own source and README before designing against it: it is explicitly “a declared, typed contract for a program’s invocation surface - argv and envp”, and every Input it declares binds to a –flag/env-var pair, never a bare positional value. Confirmed by reading argenv-cli’s own main.rs (the author’s own reference CLI): subcommand dispatch is a plain match on args.first(), not anything argenv provides. Rhizoid’s CLI follows the same shape: a thin hand-written dispatcher picks the verb and reads each command’s one primary positional (a repo spec, a URL, a module name) directly; argenv declares only the named flags for each verb.
Tags
design
Relations
← concerns: Two crates: rhizoid-core and rhizoid-cli — the cli crate is where argenvs actual scope applies
Sources
argenv

Two crates: rhizoid-core and rhizoid-cli

Summary
Mirrors argenv’s own workspace shape (crates/argenv + crates/argenv-cli). rhizoid-core holds the Manifest and Module types, their JSON Schema (via schemars, the same crate argenv itself already uses for its own contract feature), and the GitPort/GitHubPort traits the real fork/sync logic will implement later. rhizoid-cli holds argv dispatch and the per-command argenv Models. Splitting now, before there is much code, avoids a disruptive later refactor once the planned TUI needs to depend on the same core logic without the CLI.
Tags
design
Relations
→ concerns: argenv declares flags and env vars - not subcommands or positionals — the cli crate is where argenvs actual scope applies
→ pairs-with: Each fork carries its own .rhizoid/module.toml — rhizoid-core owns both the top-level manifest type and the per-fork metadata type
→ pairs-with: The manifest is TOML, with the footgun that argues against it named up front — rhizoid-core is where the TOML/schema decision actually gets implemented