Setting up Graphite in a new repository

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!

Prerequisites

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.

Step 1: Install the Graphite CLI

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

Homebrew (Recommended for macOS and Linux)

brew install withgraphite/tap/graphite

npm (For various systems)

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

Step 2: Authenticate the CLI with GitHub

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>

Step 3: Initialize Graphite in Your Repository

Navigate to your project directory and initialize Graphite:

cd path/to/your/project
gt init

Step 4: Create Your First Branch and Commit

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"

Step 5: Manage Your Stack

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.

Additional Tips

• 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.

Conclusion

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.