Everyday work

The commands you'll use most, in the order you usually use them. All of these run inside a working folder you checked out.

#See what you've changed

grixel status     # a summary: what changed, and whether you're behind the server
grixel diff       # a line-by-line diff of your edits

For a side-by-side view in a graphical tool, use grixel difftool.

#Save your work

grixel submit -m "describe what you did"

A submit is atomic — everything in it lands together. If Grixel tells you that you're behind head, someone else submitted since you last synced; run grixel sync first (below), then submit again.

#Undo local edits

grixel revert path/to/file     # discard your changes to one file

#Checkpoints: save-points before risky work

A checkpoint is a private snapshot of your changes — on your machine only, invisible to everyone else, and not a submit. Take one before a risky edit; restore it if things go wrong.

grixel checkpoint -m "rig fix done"     # snapshot your current changes
grixel checkpoint list                  # see your save-points
grixel checkpoint restore <id>          # roll back to one

Restoring is always safe: Grixel snapshots your current state first and prints the command that undoes the restore. When you're happy, submit as usual — or replay the whole stack of checkpoints as real submits:

grixel submit --from-checkpoints --squash   # one submit of the final state

Checkpoints you made on purpose are never deleted automatically while unsubmitted. They exist only on your machine until you submit, and the receipt says so every time.

#Working offline

grixel status, changes, diff, revert, and every checkpoint command work with no connection at all — diffs come from a local copy of the files you synced. If a file's local copy is missing (say, after clearing the cache), that file's diff says so plainly instead of pretending nothing changed, and heals on your next online sync. Submitting still needs the server; checkpoint your work offline and submit when you're back.

If you edit files that need locks (Photoshop files, CAD assemblies), claim them before you disconnect — see Large files and locking.

#Get the latest

grixel sync

This pulls in everyone else's submitted changes. It only downloads what actually changed, so syncing a small update to a big project is quick.

#When two people edited the same file

For text files, sync performs a three-way merge. If it can't merge cleanly it leaves a conflict, which you resolve:

grixel resolve --mine path/to/file      # keep your version
grixel resolve --theirs path/to/file    # take the server's version
grixel mergetool                        # open a merge tool to combine them by hand

Then submit the result. (Binary files can't be merged — see Large files and locking for how to avoid colliding on them in the first place.)

#Look at history

grixel log                      # recent changes to the project you're in
grixel log -oneline             # one line per commit (hash + summary)
grixel log -files               # ...also listing each commit's changed files (A/M/D)
grixel log <ref> -path <file>   # just the commits that touched one file
grixel cat <ref> <path>         # print a file as it is on the server

Each commit line shows a short hash. Paste it back to inspect that commit.

Filter history by who and when:

grixel log -author alex             # only Alex's commits (case-insensitive)
grixel log -since 2026-07-01        # commits on or after a date
grixel log -until 2026-07-15        # commits on or before a date
grixel log -author alex -since 2026-07-01 -files    # combine them

Dates are YYYY-MM-DD (midnight UTC) or a full RFC3339 timestamp.

#What changed in a commit

grixel show is the "what did this commit change" view — every file it touched, marked added (A), modified (M), or deleted (D):

grixel show <commit>              # file list for that commit
grixel show <commit> -u           # ...with the line-by-line text diffs
grixel show <commit> -u src       # ...only for files under src/

Run it inside a checkout and it uses that project's ref; elsewhere, name the ref: grixel show mystudio/games/mygame@<commit>.

#Diff between two commits

Inside a checkout, hand grixel diff two commit hashes to see everything that changed between them — the file list by default, patches with -u, and you can narrow to a subtree:

grixel diff <older> <newer>            # files changed between the two commits
grixel diff <older> <newer> -u         # ...with text diffs
grixel diff <older> <newer> art/ui     # ...only under art/ui

The same works across two different branches with their depot paths (a leading / tells grixel these are refs, not commits):

grixel diff /mystudio/games/mygame /mystudio/games/mygame-dev
grixel diff -base /mystudio/games/main /mystudio/games/feature   # only what feature added

Every form takes --json, so an assistant or script gets the changed paths, kinds, and (with -u) the diff bodies as structured data.

#Branching

Create a separate line of work and merge it back when it's ready:

grixel branch companies/acme/games/seasonal companies/acme/games/seasonal-dev
grixel checkout companies/acme/games/seasonal-dev ./dev
# ...work and submit on the branch...
grixel merge companies/acme/games/seasonal-dev    # merge it into your current checkout

#Machine-readable output

Add --json to any command to get structured output instead of text — useful for scripts:

grixel --json status