In this quick start, you will clone a new repository, use the Graphite CLI to create and manage PRs, and visualize and review changes in the Graphite web app.
After you've successfully installed and authenticated the Graphite CLI, you can use
gt commands to install and manipulate repositories and their data.
1. Create a new repository on GitHub with a
README so you can create, merge, and visualize new PRs. For this tutorial, we'll use a sample repository called
$ gt clone https://github.com/<your-repo-name>Passing command through to git...Running: "git clone https://github.com/<your-repo-name>"Cloning into 'gt-quick-start'...remote: Enumerating objects: 3, done.remote: Counting objects: 100% (3/3), done.remote: Total 3 (delta 0), reused 0 (delta 0), pack-reused 0Receiving objects: 100% (3/3), done.
Note that the output includes the statement "passing command through to git..."
gt passes unrecognizable commands through to
git so you can run commands like
gt add, and
gt status even though they aren't native commands in Graphite.
2. Enter the newly cloned repository.
$ cd gt-quick-start$ gt logGraphite has not been initialized, attempting to setup now...Welcome to Graphite!? Select a trunk branch, which you open pull requests against - inferred trunk main (autocomplete or arrow keys) ›❯ main
In an attempt to run
gt log (a command that visualizes all of the stacked branches in our repository), the CLI prompts us to initialize Graphite in this repository.
Most repositories refer to
main as their "trunk branch," or the branch you'll default to opening pull requests against. Select
main as our trunk branch by pressing enter.
3. Now, you'll see the following after running
gt log again:
◉ main (current)│ 2 minutes ago││ 2bbd959 - Initial commit│
gt log successfully outputs a graph of the branches in your repository. Right now, this only contains the initial
README commit on our default branch,
1. Edit the
$ echo 'This repo is created with Graphite!' > README.md$ gt create? You have no staged changes. What would you like to do? › - Use arrow-keys. Return to submit.❯ Commit all file changes (--all)Create a branch with no commitAbort this operation
Here's what's happening with that command:
Branches are the primary unit of change in Graphite, so the
createcommand creates a branch with your changes.
Since we did not stage our change, we are prompted to do it interactively. You can also stage changes with the
-aflag as shown in the menu.
After choosing to commit all changes, a standard
gitcommit editor will be opened, where you can type the commit message for your branch. You can also pass this into the command with the
-mflag to avoid opening an editor.
A branch name will be generated from the provided commit message. You can also provide your own branch name by passing it to the
gt createcommand as an argument.
gt log to see the new state of your repository:
◉ 02-22-editing_readme (current)│ 1 minute ago││ 6044229 - Editing README│◯ main│ 16 hours ago││ 2bbd959 - Initial commit│
You've now created and checked out a branch called
editing_readme based off of
main that contains changes to the
1. Create a few more stacked branches for the purpose of visualizing a stack in the CLI:
$ echo fizz > fizz.txt$ gt c -am "fizz"$ echo buzz > buzz.txt$ gt c -am "buzz"
You created two branches stacked on top of your previous branch that create
buzz.txt files respectively. (
c is a shortcut for
gt log again to see these changes:
◉ 02-22-buzz (current)│ 2 seconds ago││ 5c1627b - buzz│◯ 02-22-fizz│ 17 seconds ago││ 6234fb6 - fizz│◯ 02-22-editing_readme│ 10 minutes ago││ 6044229 - Editing README│◯ main│ 1 hour ago││ 2bbd959 - Initial commit│
You can also run
gt log short or
gt ls to see this graph in condensed form:
◉ 02-22-buzz◯ 02-22-fizz◯ 02-22-editing_readme◯ main
1. Create PRs for each of these branches with the
gt submit command, starting with
$ gt submit🥞 Validating that this Graphite stack is ready to submit...📝 Preparing to submit PRs for the following branches...▸ 02-22-editing_readme (Create)? Title › Editing README
You can create a title for the PR or use the default commit message,
editing README, by pressing enter.
🥞 Validating that this Graphite stack is ready to submit...📝 Preparing to submit PRs for the following branches...▸ 02-22-editing_readme (Create)✔ Title … Editing README? Body › - Use arrow-keys. Return to submit.❯ Edit Body (using vi)Skip (leave empty)
2. Next, you're asked to edit the body of the PR in
vi. It's a much better experience to use the Graphite app to edit PRs, so leave this empty for now.
🥞 Validating that this Graphite stack is ready to submit...📝 Preparing to submit PRs for the following branches...▸ 02-22-editing_readme (Create)✔ Title … Editing README✔ Body › Skip (leave empty)? Submit › - Use arrow-keys. Return to submit.❯ Publish Pull RequestCreate Draft Pull Request
3. You can publish your changes or create a draft. Choose publish for this PR.
The above process repeats for every branch in this stack, so do the same for
02-22-buzz. You should see the following output once all three branches have been published:
🥞 Validating that this Graphite stack is ready to submit...✏️ Preparing to submit PRs for the following branches...▸ 02-22-editing_readme (Create)✔ Title … Editing README✔ Body › Skip (leave empty)✔ Submit › Publish Pull Request▸ 02-22-fizz (Create)✔ Title … fizz✔ Body › Skip (leave empty)✔ Submit › Publish Pull Request▸ 02-22-buzz (Create)✔ Title … buzz✔ Body › Skip (leave empty)✔ Submit › Publish Pull Request📨 Pushing to remote and creating/updating PRs...edit_readme: https://app.graphite.dev/github/pr/withgraphite/gt-quick-start/1 (created)02-22-fizz: https://app.graphite.dev/github/pr/withgraphite/gt-quick-start/2 (created)02-22-buzz: https://app.graphite.dev/github/pr/withgraphite/gt-quick-start/3 (created)
You just created a stack of three PRs, each one dependent on the other. To keep sight of your Graphite stack when viewing the PR on GitHub, we automatically add a comment that shows you where in the stack you are with respect to the current PR. The names of the branches link to their respective pages in the Graphite app.
After submitting the three stacked pull requests, you may have noticed that the CLI produced three
app.graphite.dev links for each PR in the stack. While it's possible to merge PRs created with Graphite through GitHub, we strongly suggest merging stacks of PRs from Graphite since you can merge all your PRs in the stack at once!
To do so, click one of the
app.graphite.dev links created by the CLI to view the PR in Graphite. Notice that the
editing_readme PR has a stack indicator next to the title that says
1 of 3.
Click the dropdown, and click the top of the stack which happens to be
buzz. Notice how the stack indicator changes to
3 of 3, the status pill now says ready to merge as stack, and the merge button now says Merge 3 PRs instead of Merge.
merge 3 PRs. Once you do so, you'll see a modal with a few options to configure your merge strategy and/or edit the commit message/body for each of the PRs in the stack. Once you click to confirm the merge, you're done! Each of the PRs will merge one by one, while Graphite takes care of the pull and rebase between each.
Congrats on merging your first stack with Graphite!
This guide showed you the basics of getting started with Graphite! Check out our other docs for more specific information pertaining to the CLI or app, as well as our command reference to quickly locate
gt commands. Feel free to interact with us on Twitter, join our community Slack for a direct helpline, or shoot us an email at firstname.lastname@example.org!