Using git commands and tracking branches
Graphite's CLI features a git passthrough -
gtwill pass any unrecognized commands thru to
git, so you can run commands like
gt status, even though they aren't native commands in
git add: Stage files to be committed;
-pis helpful for precise cases.
git stash: Save changes for later (retrieve with
git stash pop). Since restacking requires the working tree to be clean, stashing changes you don't intend to commit is often necessary while using
-poption is just like
git diff: See what has changed between two branches.
git status: Keep track of your worktree and staging area, just like
git rebase: Useful for preparing branches created outside of Graphite to be tracked (see below). Also potentially dangerous (see further below).
Because of the "restacking" model, it is always safe to update your branches with simple
gitcommands as a
gt upstack restackon each child will rebase descendants such that they have the new version in their history. We specify simple here because there is some nuance to using
git rebase— see below for details.
If you use
gtto create a branch, you need to let
gtknow what its parent is. That's what
gt branch trackis for. When run, it prompts you to select a parent for the current branch from the branch's Git history.
# Ensure the branch you want to track has the desired parent in its history
# In this case, we want to stack our branch `feature` on `main`
git checkout feature
git rebase main feature
# Now, we'll track our branch
gt branch track
# If there is more than one potential parent for feature,
# you will be prompted to select one.
# Now `feature` is tracked and `main` is its parent
gt branch down # checks out main
gt branch track --forceskips the prompt and chooses the nearest ancestor that is already tracked. See the command
--helpfor more options.
What if you've created a stack of multiple branches outside of Graphite?
gt downstack trackallows you to track multiple branches recursively. Run it from the tip of a stack to track the entire thing by selecting the parent of each branch until you reach a branch that is already tracked. The
--forceflag chooses the nearest ancestor of each branch as its parent.
There is also a
gt branch untrackcommand that you can use to stop tracking a branch without deleting it from
git. Note that this will also result in all descendants of this branch becoming untracked as well; to avoid this, use
upstack ontoto move them onto a new parent first (learn more about
The CLI's engine works keeps track of the base of each branch — i.e. the commit in its history that corresponds to its parent branch. This means that if you use a vanilla
git rebasethat removes that commit from the branch's history, your branch and its children may suddenly become untracked! In order to bring the branch back into Graphite, you will need to ensure the branch is correctly based on its parent, and then use
gt trackto fix its metadata.
Rebases that don't remove that base of the branch from its history are safe — for example, running a
git rebase -ion the commits of a branch is safe, although we provide a convenience command for this called
gt branch editthat runs an interactive rebase followed by
upstack restackon each child of the branch.