Introduction

g2g is a local stacked-branch structure tool. It records a branch forest in the repository’s Git common directory, then uses that structure to inspect, restack, update and publish a stack. Recording and maintaining structure need only Git: neither Graphite nor GitHub is required.

Graphite is an optional source and alignment target. g2g can read a Graphite-described stack where one exists, adopt it into the local forest, or mirror local structure back to Graphite. GitHub is a publishing and projection integration: g2g can create pull requests, inspect their bases, and project a selected linear path onto GitHub native stacks. It never flattens a fork merely to publish it.

Every command that changes anything shows you a preview first and acts only when you add --apply, and a command that cannot tell what you meant refuses and names the command that would put things right. See Preview and apply and When a command refuses.

Where to start

• Install g2g with Homebrew.
• Read A day with g2g for the everyday loop, from recording a stack to landing it.
• Read The forest, Where structure comes from and Scope for the three ideas every command relies on.
• If an agent will run g2g for you, install the g2g skill (npx skills add shhac/agent-skills --skill g2g --global) and read Working with agents.

How the commands are arranged

Managing your own stack is the tool, so those commands sit at the top level and read like Git’s: status, create, pull, push. Anything that reaches past Git into another tool lives under that tool’s name, so a command says in its own words when it will talk to GitHub or Graphite, and someone who uses neither never has to read about them.

Heading in g2g --help	Commands
See where you are	status, doctor
Shape the stack	create, adopt, track, untrack, delete, fold, rename
Move around	up, down, top, bottom
Keep it current	restack, pull, prune
Publish and land	push, submit, land
Other tools	github (status, adopt, link, unlink, retarget, comment), graphite (adopt, mirror)

push, submit and land stay at the top level although they publish, because publishing a stack is part of managing it.

Renamed commands

The names changed in one step and no aliases were kept, so an old name is now an unknown command.

Was	Is now
graph	status
status (the pull request one)	github status
sync	pull
track --stack	adopt
import	graphite adopt or github adopt
mirror	graphite mirror
link, unlink, retarget, comment	github link, github unlink, github retarget, github comment
the pull-request source	the github source

The machine-readable output followed the same move: its operation field is now the command’s path as you would type it after g2g. See Output.

Development

g2g is written in Go and lives at github.com/shhac/g2g. To work on it, start with AGENTS.md, which holds the process knowledge, and the design doc for the area you are changing. Tests use fake executables on PATH, or throwaway local repositories where the question is what Git itself does, so they need neither authentication nor a network connection. Run them with go test ./....