To create a stack of branches with the Graphite CLI, make sure you've:
If you're familiar with the
git workflow, creating a branch and staging/committing changes shouldn't be new to you. While using a
git-style workflow to create branches in Graphite still works, we strongly recommend that you follow the Graphite workflow when creating and editing branches:
Add your changes directly on top of an existing branch. DON'T create an empty branch before doing so (we'll explain further down).
Stage these changes using
gt add -ato stage all of your files, or
gt add <FILENAME>to stage individual files
Create a new branch with these changes using
gt create ...
This follows the traditional stacked changes workflow, treating each branch as an atomic changeset that contains (at least to start with) a single commit.
Graphite generally treats branches as if they were commits. This means that something you would break up into multiple commits in a typical
git workflow, you would instead break up into multiple branches in Graphite (typically with one commit on each branch).
Here are a few ways to create a branch containing a single commit using
# navigate to the trunk branch of your repositorygt trunk# * build part 1 of your feature *# the following two commands create a new branch off of main with your changes and add a commit# add all unstaged changes (same syntax as git add)gt add -A# create a commit on a new branch with its name inferred from your commit messagegt create# OR specify your commit message via an option, just like gitgt create -m "part 1"# OR you can also specify a branch name yourselfgt create making_part_1# This works too!gt create -m "part 1" making_part_1# If you don't run `add`, you'll be prompted to add your changes interactively.# You can also run `add` as part of the create command with the `-a` flaggt create -am "part 1"# You can make the previous command even shorter by using an alias (most common gt commands have an alias, and you can even configure your own!)gt c -am "part 1"
gt create, you can decide whether to pass in a branch name. A branch name is auto-generated from your commit message if a branch name isn't provided.
You can configure a prefix for
gt create to add to all of your auto-generated branch names. See Configure the CLI for more details.
Once you've created a branch with your first set of changes, you can continue to build your stack by issuing more
gt create commands as you work.
# * build part 2 of your feature *# create a new branch on your stackgt create -am "part 2"# * build part 3 of your feature *# create another new branch on your stackgt create -am "part 3"
If you have a large branch that you want to split up into a stack of smaller branches, you can use the
gt split command. Learn more about splitting a branch.