Branching

Branching lets you work on something on the side — an experiment, a feature, a risky change — without disturbing your main line, then bring it back when it's ready.

#What a branch actually is

In Grixel a branch is a separate project path (a "ref"), not a lightweight pointer. When you branch, Grixel makes a new ref that starts as an exact copy of the source at that moment. The copy is cheap — nothing is duplicated on disk, it just shares the same content — but from then on the two refs are independent. Changes on one do not appear on the other until you explicitly merge.

If you come from Git, the difference that trips people up: a Grixel branch does not "track" its parent and it isn't a moving label on a commit graph. It's its own path with its own history. You move changes between paths on purpose, with merge.

If you come from Perforce, it's the familiar branch/stream idea: separate paths you integrate between.

So a project might have:

mystudio/games/mygame              <- your main line
mystudio/games/mygame-experiment   <- a branch to try something

Both are real, checkoutable paths.

#The workflow

Start a branch from your main line:

grixel branch mystudio/games/mygame mystudio/games/mygame-experiment
# Branched mystudio/games/mygame -> mystudio/games/mygame-experiment @ 15902d18…

Check it out into its own folder and work there — this is separate from your main checkout, so the two don't interfere:

grixel checkout mystudio/games/mygame-experiment ~/mygame-experiment
cd ~/mygame-experiment
# ...edit, grixel submit -m "...", as normal...

See how the two relate at any point (their shared starting point):

grixel merge-base mystudio/games/mygame mystudio/games/mygame-experiment

Compare them directly — what's different between the branch and main:

grixel diff mystudio/games/mygame mystudio/games/mygame-experiment

When the experiment is good, bring it back. Go to your main checkout and merge the branch into it:

cd ~/mygame                                  # your main checkout
grixel merge mystudio/games/mygame-experiment
# Merging mystudio/games/mygame-experiment into mystudio/games/mygame
#   merged (1): config.txt
grixel submit -m "merge the experiment"

merge does a three-way merge into your current working copy, so you can review the result (and settle any conflict — see below) before you submit to record it. Merging is directional: it pulls the named ref's changes into wherever you're standing.

When you're done with a branch, retire it:

grixel ref rm mystudio/games/mygame-experiment

(That removes the pointer; content that history still needs is kept.)

#The one thing to watch: binaries don't merge

This matters most for game and art projects. Text files merge line by line, so branching code is safe — two branches can edit different parts and Grixel combines them. Binary files (art, levels, audio) cannot be merged. If your main line and a branch both change the same .psd, the merge can't reconcile them; you have to pick one version (grixel resolve --mine / --theirs, or grixel mergetool for a side-by-side).

Practical rules:

• Branch code freely. That's what branching is best at.
• Be deliberate with binary-heavy areas. Avoid having two branches edit the same art at once. Keep such branches short-lived, and lean on locks (grixel edit) within a single line rather than parallel edits across branches.
• If a binary conflict does happen, it's not lost work — you choose which version wins and resubmit.

#A strategy that fits

Solo, one line. If it's just you, you often don't need branches at all — work on your main ref and submit. Reach for a branch when you want to try something risky and keep main clean: branch, experiment, merge back or throw the branch away.

A team. Give each feature or task its own short-lived branch, merge it back into main when it's ready, and delete it. Short-lived is the goal — the longer two branches diverge, the more they can collide, especially on binaries.

A protected release line. For a line you want to stay stable (a -live or -release ref), don't merge into it directly — promote reviewed content into it so it only ever accepts changes that passed sign-off:

grixel review promote mystudio/games/mygame mystudio/games/mygame-live

That's the gated version of moving changes between refs. See Review and sign-off.

#Commands at a glance

grixel branch <src-ref> <dst-ref>     # create a branch from a ref (at its head, or -rev)
grixel checkout <ref> <dir>           # work on a branch in its own folder
grixel merge <src-ref>                # merge a ref into the current checkout
grixel merge-base <ref-a> <ref-b>     # the shared starting point of two refs
grixel diff <ref-a> <ref-b>           # what differs between two refs
grixel review promote <src> <dst>     # move approved content to a protected ref
grixel ref rm <ref>                   # retire a branch when you're done