Beagle SCM

Submodules: nested projects mounted as secondary worktrees

A submodule splits a project into smaller reusable parts or vendors a dependency; the goal is a seamless recursive experience where clone, checkout, and commit descend into subs by default. The method reuses Beagle's own machinery: a submodule is just another project in the parent's Store, checked out as a secondary worktree at the gitlink path. Git stays byte-exact — a 160000 gitlink and a root .gitmodules blob name the pin and upstream.

• submodule tips are tracked by synthetic branches, e.g. /subproject/.parent/.grandparent/gp_branch;
• the logic is URI recursion driven, e.g. get be://store?/parent invokes get be://store?/submodule in a subdir;
• dirtyness accounts for submodule changes too (dirty if contains anything dirty);
• store layout: .be/project/..., i.e. flat at the store level;
• submodule run reports get aggregated into parent reports;
• submodules traversal depends on a verb (e.g. preorder for get, postorder for post);
• recursion is the default, every verb descends into subs, --nosub opts out.

Recursion

1. GET - clone/update:
   • pre-order (parent creates/updates all files before a child),
   • checkout commits are taken from parent's gitlink,
   • tries to retrieve the child files from the same source, falls back to .gitmodules URI,
   • child worktree tracks a synthetic branch, e.g. /child/.parent/parent_branch
2. POST - commit/advance:
   • post-order (child commit hash is known before parent can commit),
   • child commit is recorded into parent's gitlink,
   • for wire-posts (pushes) tries to push child changes into the same remote,
   • child worktree commits update the local synthetic branch,
3. PUT, DELETE - stage:
   • pre-order, in a sense: staging a submodule file delegates that to submodule,

     then stages that submodule;

4. HEAD - fetch:
   • pre-order, same as get.

Store layout

A submodule is just another project shard in the parent's store, mounted as a secondary worktree that points back; there is no separate submodule store class. The parent tree's 160000 gitlink pins which commit, the root .gitmodules blob names where to fetch it.

• The sub's objects sit in .be/<title>/, same level as the parent's, see Store,
• The shard's Title comes from the .gitmodules URL basename, .git and trailing / stripped (…/libabc.git → libabc).
• Submodule worktree log is at <wt>/<path>/.be (same structure at the root wtlog),
• Sub of a sub still stores as .be/<title>/, synthetic branches /<title>/.<parent>/.<grandparent>[/<gp_branch>].