Skip to main content

​
Configuration options

Run gt config to open an interactive menu which lets you configure your Graphite CLI. The options are described in more detail below.

​
User-level configuration

​
Branch naming settings

If you don’t specify a name for your branch when using gt create, then Graphite will generate one for you based on the commit message. There are several options to configure:
  1. A custom prefix (for example, initials).
  2. Whether or not the date is prepended to the branch.
  3. Whether to allow certain characters like slashes and uppercase letters
  4. The character to replace unsupported symbols (for example, whitespace and anything other than alphanumeric characters, periods, dashes, underscores, and slashes.)

​
Submit settings

Set PR metadata in CLI Graphite lets you prepare your PR for review in the web UI by default. This allows you to preview markdown, pull options like reviewers and labels from downstack PR’s, and update all PR’s in a stack at once. Enable this setting to instead default to writing PR description in the CLI. PR description Graphite includes your GitHub PR template in the commit message by default. Graphite can include the commit messages of your branch in the body of your PR automatically on submit. If you enable this, you can choose whether or not to also include your PR template. If you only have a single commit on your branch, the first line of the message (its title) will not be included as this is already the default for the name of the PR.

​
Rebase behavior

The git rebase flag --committer-date-is-author-date is useful if you don’t want your Graphite restack operations to update the committer date of the commits in your branches. In order to have Graphite’s internal rebases use this flag, you can enable this configuration.

​
Sync settings

Toggle to automatically delete merged or closed branches during gt sync and gt get operations.

​
Empty branch settings

Specify how Graphite should handle empty branches after an operation (keep or delete).
Default utilities
By default, Graphite uses the git editor for drafting PR descriptions and other flows that require editing text. You can configure a different editor. By default, Graphite opens PR descriptions and other flows that require editing text in the git pager. You can configure a different pager, or disable paging entirely. Note that just like git, Graphite sets the environment variables LESS=FRX and LV=-c if they are not already set. If something else is setting your LESS env var, you can use gt user pager --set "less -FRX" to get the recommended pager settings.
You can also set the editor or pager on a per-command basis with the GT_EDITOR and GT_PAGER environment variables, respectively.

​
Tips

Toggle on and off inline tips in the Graphite CLI.

​
Yubikey

If you use a Yubikey to protect your GitHub SSH key, you may be used to Git commands reminding you to touch it. Graphite is not able to print this output directly to the CLI due to how Git calls SSH, so you can enable this configuration to be reminded when Graphite is about to run a command that requires you to touch your Yubikey.

​
Update settings

You can individually enable or disable automatic updates and update prompts. As of version 1.7.4, gt is able to automatically update in the background. These automatic updates are disabled by default for existing gt installs that get updated to 1.7.4 or higher. They are enabled by default for new gt installs. The configuration for automatic updates and update prompts gets set in the ~/.config/graphite/user_config file: 
"updateAutomatically": true,
"promptForUpdates": true,

​
Set default profile

See how to configure multiple profiles in Profiles and authentication. Set your profile by running gt config -> Set default profile to see a list of your alternative profiles:
Press return on your desired profile to set your new default profile:

​
Repository-level configuration

Repository-level configuration is stored in the .git folder of your repository.

​
Trunk branches

Configure one or more trunk branches. For developing on multiple trunk branches see our tutorial here.

​
Git remote name

Graphite defaults to pushing to and pulling from origin. If you have configured a different name for your remote, you can set it manually.

​
GitHub repository information

Once the remote URL is set, Graphite infers the GitHub repository name and owner from the remote URL, but in cases where they are not inferred correctly, you can override them.

​
User configuration file

User configuration for Graphite CLI gets stored in the user_config file in the ~/.config/graphite/ directory. This user configuration applies globally when executing gt commands. To apply a different user configuration locally, such as if you work with clones of the same repo and want different branch name settings for each, you can create a user_config file in another directory and set the $XDG_CONFIG_HOME environment variable to that directory’s path.

​
Profiles and authentication

​
Using Graphite CLI with multiple GitHub user accounts/auth tokens

Multiple profiles are supported from gt version 1.7.2 onwards
In your ~/.config/graphite/user_config file you can set alternative named profiles so that each can make use of separate authentication tokens. Profile names and your default profile selection live in user_config. For gt version 1.8.4 and later, the corresponding tokens can be stored in ~/.config/graphite/auth (see more in Auth file). On older versions, or as a fallback, tokens can be stored directly in user_config.

​
Example user_config file

Example showing user_config with just profile names (tokens would be stored in the auth file): 
{
  "profile": "work_github_account",
  "alternativeProfiles": [
    {
      "name": "work_github_account"
    },
    {
      "name": "personal_github_account"
    }
  ]
}
Example showing you can keep tokens inline in user_config (supported on all versions with multiple profiles): 
{
  "alternativeProfiles": [
    {
      "name": "work_github_account",
      "authToken": "xxxx"
    },
    {
      "name": "personal_github_account",
      "authToken": "xxxx"
    }
  ]
}
You can also name one of the profiles as “default” for it to always be used when not specifying in gt config or GRAPHITE_PROFILE environment variable: 
{
  "alternativeProfiles": [
    {
      "name": "default",
      "authToken": "xxxx"
    },
    {
      "name": "personal_github_account",
      "authToken": "xxxx"
    }
  ]
}

​
Profile precedence

Run gt auth to verify the current active profile and authenticated GitHub login.
When resolving which profile is active, gt checks (in order):
  1. GRAPHITE_PROFILE environment variable (overrides the saved default)
  2. profile field in user_config (set via gt config → Set default profile)
  3. A profile named "default" in user_config.alternativeProfiles
The Set default profile option in gt config only lists profiles defined in user_config.alternativeProfiles. A profile can exist only in auth if you select it with GRAPHITE_PROFILE, but it will not appear in the gt config profile picker until you add the name to user_config.

​
Auth file

The dedicated auth file is supported from gt version 1.8.4 onwards.
Graphite can store authentication tokens separately in ~/.config/graphite/auth instead of ~/.config/graphite/user_config. When you run gt auth --token <token>, the CLI saves the token to the auth file by default. If the auth file cannot be written, gt falls back to user_config and prints a warning. The auth file uses the same alternativeProfiles JSON schema as the user_config does for multiple profiles. Each profile object supports:
  • name (required)
  • authToken (optional)
You can store a top-level authToken for the default profile, or define per-profile tokens under alternativeProfiles with matching name values. If the active profile is "default" and a matching entry exists in alternativeProfiles, that profile’s token takes precedence over the top-level authToken.

​
Example auth file

For a single default account: 
{
  "authToken": "xxxx"
}
For multiple accounts, store tokens in auth with profile names that match those in user_config: 
{
  "alternativeProfiles": [
    {
      "name": "work_github_account",
      "authToken": "xxxx"
    },
    {
      "name": "personal_github_account",
      "authToken": "xxxx"
    }
  ]
}

​
Auth token precedence

Run gt auth to verify the current active profile and authenticated GitHub login.
When resolving which token to use, gt checks (in order):
  1. GRAPHITE_AUTH_TOKEN environment variable (if set, always wins)
  2. ~/.config/graphite/auth for the active profile
  3. ~/.config/graphite/user_config (legacy fallback if the auth file is missing, unreadable, or has no token for that profile)
If both files contain tokens for the same profile, auth is used and any matching token in user_config is ignored. You can remove legacy authToken fields from user_config to avoid confusion.

​
Overriding profiles and auth tokens with environment variables

You can set the GRAPHITE_PROFILE environment variable with the name of the profile you want to run gt commands with: 
GRAPHITE_PROFILE=work_github_account gt sync
The GRAPHITE_AUTH_TOKEN environment variable is supported from gt version 1.8.3 onwards
You can set the GRAPHITE_AUTH_TOKEN environment variable to override authentication tokens from config files and profiles. This is useful for CI/CD pipelines, containerized environments, or any context where you don’t want to rely on a config file. 
GRAPHITE_AUTH_TOKEN=your-token gt sync

​
Set up shell completion

Graphite supports zsh, bash, and fish tab completion. You can run one of the following commands:

​
For zsh

Terminal
gt completion >> ~/.zshrc

​
For bash

Terminal
gt completion >> ~/.bashrc
or
Terminal
gt completion >> ~/.bash_profile

​
For fish

Terminal
gt fish >> ~/.config/fish/completions/gt.fish

​
Set up aliases for Graphite CLI commands

You can set aliases for gt commands and customize the flags that commands will be run with. Aliases get stored in the aliases file in the ~/.config/graphite/ directory. They will apply globally when executing gt commands. Run gt aliases as a shortcut to open the aliases file in your terminal’s default editor. Aliases for ss, ls, and ll are defined by default. If you delete this file, it will be recreated with the default aliases. The first word of each line in the file is the alias, the second is the command and the following words are the flags. Lines starting with # are ignored:
aliases
# this line is ignored
ls log short
ll log long
ss submit --stack