quixos/BRANCHING.md

Branching Quixos Stacks

This note is for working directly in the Quixos workspace when continuing from an older outer-repo snapshot.

Problem

The outer repo pins package repos by submodule commit. If you check out an older outer-repo commit, the package repos usually land on detached HEADs at the older pinned commits.

That snapshot is still valid, but it is awkward to continue development from there because package repos do not have active local branches or upstreams.

Tool

Use:

utils/branch-stack.sh <branch>

Example:

utils/branch-stack.sh feature/snapshot-recovery

This will:

1. create or switch the outer repo to <branch>
2. create or switch the same branch in each non-ignored package repo under packages/
3. push each branch to origin and set upstreams

Variants

Branch only selected package repos:

utils/branch-stack.sh feature/snapshot-recovery root matrix-bot

Create the branches locally without pushing:

utils/branch-stack.sh feature/snapshot-recovery --no-push

Include ignored package repos too:

utils/branch-stack.sh feature/snapshot-recovery --include-ignored

Recommended workflow

1. Check out the older outer-repo snapshot you want.
2. Run utils/branch-stack.sh <branch>.
3. Continue normal work from there, including qx-control stage ....

Create-package behavior

qx-control create-package now uses the current outer repo branch by default.

You can also force a branch explicitly:

qx-control create-package my-package --template typescript --branch feature/foo