Quick start
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.
Prerequisites
Basic understanding of GitHub and
git.The Graphite CLI is installed and authenticated.
Clone a repository
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-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.
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 clone, 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, main.
Create the first branch in a stack
1. Edit the README file:
$ 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
--allor-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--messageor-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.
2. Run 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 README.md file.
Add to the stack
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 fizz.txt and buzz.txt files respectively. (c is a shortcut for create.)
2. Run 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
Submit a stack
1. Create PRs for each of these branches with the gt submit command, starting with edit_readme.
$ 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-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...▸ 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.
Merge a stack of PRs from 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.
Click 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!
Join the Graphite community
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 support@graphite.dev!