Repository navigation
CODE: garden tools
(private) Top Level Wiki
(private) Feralcoder IT
cornucopulator
fcdocs
fcenv
MusicMind
A catalog is a named logical collection of repos (submodules) at published versions, implemented itself in a repo. It is a lightweight umbrella: a list of names, URLs, and SHAs. Its weight is entirely referential — it points at things; it does not contain them.
A garden is a physical catalog checkout — a live working instance on a specific machine. It is frequently on a branch of the same name (eg the AI_Tools garden lives in branch "AI_Tools"). Its submodules may be on their own branches of same or different name.
A garden is reconstructible: delete it and rebuild it from the catalog in minutes. Its definition (branch, policy, IDE wiring) lives on the garden branch.
One catalog → many gardens (different machines, different branch policies).
One of the submodules in all gardens is garden-tools, which provides the bootstrap scripts, policy hooks, and lifecycle tooling described below.
CODE: https://github.com/feralcoder/garden-tools
WIKI: https://github.com/feralcoder/garden-tools/wiki
git config --global garden.codeRoot ~/Workspace/repos/workspace
git config --global garden.gardenRoot ~/Workspace/repos/GARDENS
git config --global garden.catalogRoot ~/Workspace/repos/CATALOGS
# POR EXEMPLO:
CATALOG=cornucopulator
GARDEN=AI_Tools
GARDEN_HOME=~/Workspace/repos/GARDENS # Here's where we'll work in the AI_Tools garden
CATALOG_HOME=~/Workspace/repos/GARDENS/_CATALOGS # Catalog/Garden Metadata DON'T MESS HERE
CODE_HOME=~/Workspace/repos/workspace # Standalone Code Checkouts Here
mkdir -p $CODE_HOME $CATALOG_HOME $GARDEN_HOME/$CATALOG && cd $CATALOG_HOME
To check out the existing shared garden on a particular location:
# 1. Clone the catalog repo
git clone git@github.com:feralcoder/$CATALOG.git catalog-$CATALOG
cd catalog-$CATALOG
# 2. Initialize submodules defined by the catalog (incl. garden-tools)
git submodule update --init
# 3. Stand up the AI_Tools garden — creates the garden worktrees and
# clones the child repos defined in .garden-catalog
./garden-tools/scripts/garden-init.sh $GARDEN $GARDEN_HOME/$CATALOG/$GARDEN garden/$GARDEN
# 3a. That failed, wrong paths.
# Next command won't fail, when you're ready to run it.
# Script infers catalog/garden roots from us, here, now (running from catalog-$CATALOG/garden-tools/...)
# ./garden-tools/scripts/garden-init.sh $GARDEN $GARDEN_HOME/$CATALOG/$GARDEN garden/$GARDEN --install-missing-hooks --refresh-hooks --code-root ~/Workspace/repos/workspace/
# 3b. That may fail if working garden-tools not yet checked out
# ./garden-tools/scripts/garden-init.sh $GARDEN $GARDEN_HOME/$CATALOG/$GARDEN garden/$GARDEN --install-missing-hooks --refresh-hooks --code-root ~/Workspace/repos/workspace/ --xxxx
That produces:
- $GARDEN_HOME/$CATALOG/$GARDEN — garden worktree on garden/$GARDEN with all submodules checked out on their target branches
- $GARDEN_HOME/$CATALOG/$GARDEN-main (or {name}-main) — the read-only base mirror worktree
cd $GARDEN_HOME/$CATALOG/AI_Tools
./garden-tools/scripts/garden-refresh-base.sh --include-utility --execute # pull bases, merge up
./garden-tools/scripts/garden-push-state.sh --include-utility --execute # push state (dry-run without --execute)
Each catalog has one canonical clone (object store) plus garden directories as linked git worktrees on that shared store. Child repos worktree the same way on their own object stores:
workspace/feralcoder/catalog-{name}/ ← canonical catalog clone (main)
GARDENS/{name}/{Garden}/ ← catalog worktree (garden branch)
GARDENS/{name}/{Garden}/{child}/ ← child repo worktree (garden branch)
-
catalog
main— distributable snapshot, submodule-pinned. Immutable history. -
catalog
garden/<Name>— garden definition:.gitignore,.worktree-policy,.devin/(IDE face), installers. -
child
main— upstream/distribution base, fast-forward only. -
child
utility— shared writable integration branch pinned by garden snapshots.
- Conceptual submodule — part of the garden's working concept. Worktrees in on the garden branch, participates in garden branch policy, pinned at a garden-specific SHA.
-
Utility inclusion — glue that makes the machinery work (eg
garden-tools,thoughtVaultClients). Does not participate in concept policy.
-
.worktree-policyat each worktree root declares desired branch, enforcement level (advisory/warn/block), and whether branch switching is allowed. -
Catalog hooks install once on the canonical catalog clone and are shared by all catalog worktrees (
establish-catalog-hooks.sh). -
Repo hooks install once per child/utility object store (
install-worktree-hooks.sh). - Hooks fire on
post-checkout,post-merge,pre-commit: desired-branch checks, singleton locks, submodule alignment, branch-switch blocks.
- Advisory — normal working surface. Warns on policy violation, never blocks.
- Singleton — locked working surface, branch switching blocked. Used for sync bridges (Obsidian sync), read-only mirrors, controlled ingest points.
-
garden-checkout.sh— position branches across the garden (positioning ≠ synchronization). -
garden-refresh-base.sh/garden-sync-up.sh— pullorigin/main, merge main upward. -
garden-snapshot.sh— commit current submodule refs (gitlinks) to the garden branch. -
catalog-snapshot.sh— publish garden state back to catalog/submodule base branches. -
garden-push-state.sh— push target/base/mirror branches without force.
git clone <catalog-remote> workspace/feralcoder/catalog-<name>
cd workspace/feralcoder/catalog-<name>
git submodule update --init # gets garden-tools
./garden-tools/scripts/establish-catalog-hooks.sh
./garden-tools/scripts/garden-init.sh <garden-name> <path> <branch>cornucopulator is my whole set of AI tools and knowledge.
Type: advisory — desired_branch = garden/AI_Tools, warns never blocks.
Conceptual (on garden/AI_Tools): thoughtVault, thoughtVaultMCP, thoughtVaultClients, thoughtVaultDockets, dworkinsPattern, machine-ops.
Utility: garden-tools (base main, target utility).
Note thoughtVaultClients is conceptual here but utility in other gardens — role is per-garden, not per-repo.
fcdocs is the collection of scattered feralcoder documentation sources — realized on disk as the three old wikis plus thoughtVault.
Type: advisory — desired_branch = garden/First_Docs.
Conceptual: workstation.wiki (old private wiki), shared.wiki (old public wiki), feralcoder.github.io.wiki (github.io wiki), thoughtVault.
Utility: garden-tools.
oneNote is not (yet) a submodule — it lives outside as GARDENS/oneNote_Obsidian_Exports, an unmanaged staging dir.
fcenv is the collection of tools and configurations used to build specific feralcoder environments.
Type: advisory — desired_branch = garden/cliff-dev.
Conceptual: machine-ops (ansible), workstation, bootstrap-scripts, myenv, machine-bootstrap.
Utility: garden-tools, plus thoughtVaultClients pinned on main.
The Obsidian↔git sync bridge — the production example of a singleton garden.
Type: singleton — enforcement = block, allow_branch_switch = false, lockfile /tmp/frutenlumens-obsidian.lock. Changes aggregate one-way on garden/Obsidian_Sync, then promote to main on schedule.
Conceptual: thoughtVault, thoughtVaultDockets, thoughtJournal.
Utility: garden-tools, thoughtVaultClients (both on main).
Not on disk yet. A curated subset of First_Docs, for publication. Likely advisory, with the wiki repos as conceptual inclusions and a stricter publish flow via catalog-snapshot.sh.
Not on disk yet. A curated and staged set of my AI tools for a client or employer — same catalog as AI_Tools, different garden branch and submodule subset.