Graphite quick start
This guide relies on a basic understanding of using GitHub and git and will show you how to clone a brand new repository, use the Graphite CLI to create and manipulate PRs, and visualize/review changes in the Graphite web UI.
Installation and authentication of the CLI
Follow instructions to install and authenticate the CLI before getting started.
Cloning a repository
Now that you've successfully installed and authenticated the Graphite CLI, we can start using gt commands to install and manipulate repositories and their data. Start by creating a brand new repository on GitHub with a README so that you can create, merge and visualize new PRs.
For the sake of this tutorial, we'll be using a sample repository called gt-quick-start:
$ 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.
Notice that the output includes the statement "passing command through to git..."
Part of what makes using the Graphite CLI so easy is the fact that it uses git passthrough. In other words, gt passes any commands it doesn't recognize through to git so that you can run commands like gt clone, gt add and gt status even though they aren't native commands in Graphite.
Let's 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
We tried to run gt log (a command that visualizes all of the stacked branches in our repo) but since we haven't initialized Graphite in this repository yet, the CLI prompts us to do so. Most repositories refer to main as their "trunk branch," or the branch you'll default to opening pull requests against.
Let's go ahead and select main as our trunk branch by pressing enter.
? Would you like to start tracking existing branches to create your first stack? › (y/N)
The next question the CLI asks us is if we want to track existing branches or if we want to start fresh. Since this repository was created from scratch and we don't have existing branches to track, let's select "no" here. In the future if you are initializing Graphite on an existing repository that already contains important branches, you can track them during this step.
Let's try running gt log again:
◉ main (current)│ 2 minutes ago││ 2bbd959 - Initial commit│
We're in business! 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, main.
Creating the first branch in a stack
Since gt has git passthrough, many of these commands will feel similar to those used in git to create, track, and commit changes. You'll notice a slight difference in workflow - we discuss this more in depth here if you're interested in the differences between a typical GitHub workflow and a trunk-based development workflow.
To start, let's edit the README file for our first change:
$ echo 'This repo is created with Graphite!' > README.md$ gt branch create -a -m "Editing README" edit_readme
Whoa, that last command looks kind of crazy - let's break it down.
Branches are considered the major unit of change in Graphite, which is why we created a suite of gt branch commands to operate on your current branch. After adding our changes to README.md, we want to stage those changes (the -a tag) and commit them to a new branch (with the argument to the -m tag serving as the commit message). edit_readme is used as the name of this new branch - if this isn't provided, a combination of the current date + initial commit message is automatically used as the name of the new branch.
Since the stage/commit/branch workflow is so common, we will generally do all of these commands in-line as we did above. However, you could break these operations down into gt add . and gt branch create -m "Editing README" edit_readme if you prefer.
Let's run gt log to see the new state of our repository:
◉ edit_readme (current)│ 1 minute ago││ 6044229 - Editing README│◯ main│ 16 hours ago││ 2bbd959 - Initial commit│
Fantastic, we've now created and checked out a branch called edit_readme based off of main that contains our changes to the README.md file.
Adding to the stack
Let's create a few more stacked branches for the purposes of visualizing a stack in the CLI:
$ echo fizz > fizz.txt$ gt bc -a -m "fizz"$ echo buzz > buzz.txt$ gt bc -a -m "buzz"
We just created two branches stacked on top of our previous branch that create fizz.txt and buzz.txt files respectively. Notice that we use bc as a shortcut for branch create.
Let's once again run gt log to see these changes:
◉ 02-22-buzz (current)│ 2 seconds ago││ 5c1627b - buzz│◯ 02-22-fizz│ 17 seconds ago││ 6234fb6 - fizz│◯ edit_readme│ 10 minutes ago││ 6044229 - Editing README│◯ main│ 1 hour ago││ 2bbd959 - Initial commit│
We can also run gt log short or gt ls to see this graph in condensed form:
◉ 02-22-buzz◯ 02-22-fizz◯ edit_readme◯ main
Since we didn't explicitly provide gt bc with a branch name, it set the date + the commit message as the default branch name here. You can use gt branch down or gt branch up commands to move up and down the branches in this stack. By default, gt branch down|up has a step value of 1, but you can specify gt branch down|up <step number> to jump between a set number of branches in a stack.
Submitting a stack
Let's create PRs for each of these branches! We can do this with the gt stack submit command which will walk us through the process of creating PRs for each of the three branches in the stack we just created, starting with edit_readme.
$ gt stack submit🥞 Validating that this Graphite stack is ready to submit...📝 Preparing to submit PRs for the following branches...▸ edit_readme (Create)? Title › Editing README
We're asked to input a title for the PR, but we can also use the commit message, editing README, as the default by pressing enter.
🥞 Validating that this Graphite stack is ready to submit...📝 Preparing to submit PRs for the following branches...▸ edit_readme (Create)✔ Title … Editing README? Body › - Use arrow-keys. Return to submit.❯ Edit Body (using vi)Skip (leave empty)
Next, we're asked to edit the body of the PR in vi. Many of our engineers prefer using the Graphite dashboard to edit their PRs, so we'll go ahead and skip this for now. We'll talk more about using the dashboard later.
🥞 Validating that this Graphite stack is ready to submit...📝 Preparing to submit PRs for the following branches...▸ edit_readme (Create)✔ Title … Editing README✔ Body › Skip (leave empty)? Submit › - Use arrow-keys. Return to submit.❯ Publish Pull RequestCreate Draft Pull Request
Finally, we're asked if we want to publish our changes or create a draft. Let's go ahead and publish this PR.
The above process repeats for every branch in this stack - go ahead and do the same for 02-22-fizz and 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...▸ edit_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)
Let's go! We just created a stack of 3 PRs, each one dependent on the other. So that you don't lose 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 dashboard.
Getting started with the Graphite dashboard
After submitting the three stacked pull requests, you may have noticed that the CLI spat out three app.graphite.dev links for each PR in the stack respectively. Let's follow the edit_readme link to see what this PR looks like on the Graphite dashboard.
If it's your first time using the Graphite dashboard, you'll have to sign in with your GitHub account and give Graphite access to your repositories. You'll be prompted to authorize via the GitHub app and specify which orgs/repositories Graphite will have access to - read more about Graphite dashboard setup instructions here.
Finally, you'll be asked to select a default repository - make sure you select the repository we've been working on up until now. In our case, it's withgraphite/gt-quick-start. You can later re-configure this to include all of the repositories you're interested in.
Anatomy of the PR page
Let's get back to editing the metadata of the PRs we just created. After following the link next to the edit_readme branch in the CLI, you should see something like this:
The PR page has a few main parts:
The header: This is where you can see the PR's mergability, the PR title (which you can edit by hovering over and clicking the pencil icon), the PR# and author, as well as options to add comments, merge, and the version history of the PR.
The description: Just under the header to the left, you can edit the PR's description with an interactive markdown experience. Drag and drop screenshots and screen recordings, add emojis, and even GIFs into the PR body. You can configure PR descriptions to follow specific templates. One of our newest features, AI summarize, use GPT3 to auto-populate the summary of your PR based on its diff contents.
The diff: Under the description you have the most important part of the PR, the diff. Here you can see what changed between the original state of the repository (left) and the changes introduced by this PR (right) in a split-view. If you prefer a unified diff view, you can toggle between the two under the
...menu on the PR header. You can leave comments on a diff by clicking/dragging your cursor along the line numbers of the code block.Information panel: To the right of the description and diff is the PR's information panel. This panel displays the PR's general info by default, but has several other tabs that contain relevant PR information as well.
General info: contains information about the PR's repository/branch name/parent branch, merge conflicts indicator, live-updating CI status, and a section to see and add reviewers for the PR
Files: an active filetree for the PR
Stack: an interactive version of
gt logfor the stack that this PR is a part of. You can switch between PRs in the stack by clicking on their titles and see their mergability at a high levelTimeline: similar to the GitHub timeline, you can see all activity related to the current PR including issue-level comments, threaded, comments, version updates, and more
Threads: on longer diffs, conversation threads can get buried and hard to find. The threads tab allows you to quickly see all in-line comment threads regardless of where they exist in the code
Merging a stack
As a final step, we want to merge all three PRs as a stack of changes into trunk. Doing so is very simple with the Graphite dashboard!
First, we'll navigate to the "stacks" tab on the information panel:
From here, we can see that we're currently viewing the first PR in the stack and have the option to merge it independently. Since all three PRs are ready to merge, let's click on buzz, the furthest PR upstack:
You'll notice that the merge button's text changed from merge to merge stack of 3. Let's go ahead and merge the stack:
PR inbox and review queue
At any point during your workflow, you can visit app.graphite.dev to check or review PR statuses. After merging our stack of three, if you go back to the main dashboard you should see something like this:
Notice that all three PRs that we've merged appear in the merged or recently merged section. These sections are entirely configurable - the six we've provided are suggestions for sections we find ourselves most commonly using.
Join the Graphite community
This guide should have showed you the basics of getting started with Graphite! Check out our other docs for more specific information pertaining to the CLI or Dashboard, 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 hello@graphite.dev!