Setting up Graphite in a new repository

Greg Foster
Greg Foster
Graphite software engineer

Welcome to Graphite! This guide will walk you through setting up Graphite for your new repository. Graphite is a powerful tool that enhances your development workflow by enabling trunk-based development with stacked changes and simplified code reviews. Let's get started!

Before you begin, ensure you have the following:

  • A GitHub account with an existing organization.

  • GitHub organization owner permissions (or the ability to request installations if you're not an owner).

  • An existing repository or a new one with at least one commit.

Graphite's CLI tool is the gateway to using all its features. Choose your preferred installation method:

brew install withgraphite/tap/graphite
npm install -g @withgraphite/graphite-cli@stable

After installation, you must authenticate the CLI with your GitHub account.

  1. Visit Graphite Activation and sign in with your GitHub account.

  2. Run the authentication command provided in your terminal:

gt auth --token <YOUR_AUTH_TOKEN>

Navigate to your project directory and initialize Graphite:

cd path/to/your/project
gt init

Start making changes on an existing branch and then use Graphite commands to commit those changes:

# Add your changes
gt add .
# Create a new branch and commit your changes
gt branch create -m "Your commit message"

Once you have changes ready, manage your stack with the following command:

gt stack submit

This will create pull requests for each branch in your stack on GitHub.

  • Keep Pull Requests Small: Graphite encourages small, manageable pull requests for easier review and faster integration.

  • Sync and Restack Often: Regularly sync your trunk branch and restack your work to prevent conflicts.

  • One Commit Per Branch: Aim for a single commit per branch within your stack for clarity and simplicity.

With these steps, you should have Graphite set up for your new repository. For any further details on commands and features, refer to the full CLI documentation. If you encounter any issues or have questions, Graphite's support is ready to assist you.

Give your PR workflow
an upgrade today

Stack easier | Ship smaller | Review quicker

Or install our CLI.
Product Screenshot 1
Product Screenshot 2