Git Branch Mixer

Git Branch Mixer

ggmx (git mix) configures named sets of branches to merge together. ggmxd (git mixdown) executes a mixdown — resetting a target branch to a base and merging all the other branches in.

The typical use case is testing a combination of feature/bugfix branches together via a throw-away temporary working branch.

Critical rule: mixdown target branches (especially working) are local throw-away integration branches. Never push a mixdown target branch, create a PR from it, or otherwise publish it unless the user explicitly asks for that exact action. Independent source branches may be pushed as needed, but the mixed working branch stays local by default.

Default location: when producing a mixdown for the working branch, run it from the repository's main checkout, not from a linked worktree, unless the user specifies another location. The main checkout is normally where the combined software is built, run, and tested; source branches may still live in linked worktrees. Because the mixdown checks out and resets working, stop and ask before stashing or otherwise moving aside changes from a dirty main checkout.

Configuring mixes with ggmx

ggmx                          # show all configured mixes
ggmx <target>                 # show branches in mix for <target>
ggmx <target> A B C           # set mix for <target> to branches A, B, C
                               # (first branch is the base)
ggmx [<target>] +D [-B]       # add D to / remove B from mix for <target>
                               # (defaults to 'working' if <target> omitted)
ggmx -d <target>              # delete the mix for <target>

Mixes are stored in git config under mixdown.<target>. You can also edit them directly with git config --edit.

Running a mixdown with ggmxd

ggmxd                          # run mixdown using config for default target ('working')
ggmxd -b <target>              # run mixdown using config for <target>
ggmxd BASE B1 [B2 ...]         # explicit mixdown: reset to BASE, merge B1, B2...
ggmxd -b <target> BASE B1 ...  # explicit mixdown into named target branch

Always pass -c / --checkout to leave the target branch checked out after the mixdown, ready for testing:

ggmxd -c                       # mixdown from config, stay on target branch
ggmxd -c BASE B1 B2            # explicit mixdown, stay on target branch

Without -c, ggmxd restores your previously checked-out branch after completing the mixdown. Use this when you want to rebuild the mix in the background without switching away from your current branch.

After a successful mixdown, if the combined software can be run or otherwise tested, rebuild it and restart the running instance from the main checkout before reporting it ready. A mixdown that has not reached the user's actual test environment is not complete.

Other options

ggmxd -s STRATEGY              # set merge strategy (default: octopus)
                               # use e.g. -s recursive for sequential merges
                               # with conflict resolution shells between each

After changing a mix

After any ggmx operation that modifies a mix (adding, removing, or setting branches), always ask the user whether they want to run a mixdown now.

Typical workflow

# One-time setup: configure the mix for the 'working' target branch
ggmx working main feature/foo bugfix/bar

# Add another branch later
ggmx +feature/baz

# Run the mixdown and stay on the result for testing
ggmxd -c

# Rebuild after rebasing one of the branches
ggmxd -c