Authenticate the CLI with Graphite’s API

gt auth --token graphite_cli_auth_token

Motivation: Before using the gt command, it is necessary to authenticate the CLI with Graphite’s API. This ensures that the commands executed by the CLI are authorized and can interact with the necessary repositories.

Explanation: The auth --token subcommand is used to authenticate the CLI. graphite_cli_auth_token should be replaced with a valid authentication token generated from Graphite’s API. This token can be obtained by following the instructions provided in the documentation.

Example output:

Successfully authenticated with the Graphite API.

Initialise gt for the repository in the current directory

gt repo init

Motivation: Initializing gt for the repository in the current directory allows for the creation and management of sequences of dependent code changes.

Explanation: The repo init subcommand is used to initialize gt for the repository. This command should be run in the root directory of the repository where you want to use gt. It sets up the necessary configuration files to enable gt to track and manage code changes effectively.

Example output:

Initialized gt for the repository.

Create a new branch stacked on top of the current branch and commit staged changes

gt branch create branch_name

Motivation: Creating a new branch and committing staged changes becomes necessary when you want to separate different sets of code changes or work on a specific feature independently.

Explanation: The branch create subcommand is used to create a new branch. branch_name should be replaced with the desired name for the new branch. The new branch is stacked on top of the current branch, meaning it contains all the code changes present in the current branch. If there are any staged changes, they will also be committed automatically.

Example output:

Created branch branch_name on top of the current branch.

Create a new commit and fix upstack branches

gt commit create -m commit_message

Motivation: Creating a new commit is essential when you have made changes to the code and want to save those changes as a separate revision. Fixing upstack branches allows for incorporating the changes made in the current branch into the dependent branches.

Explanation: The commit create subcommand is used to create a new commit. -m specifies the commit message that describes the changes made in the commit. commit_message should be replaced with an informative commit message. This command automatically creates a new commit and includes it in the current branch. Additionally, it fixes upstack branches, which means it incorporates the changes made in the current branch into the dependent branches.

Example output:

Created commit with message "commit_message".
Fixed upstack branches.

Force push all branches in the current stack to GitHub and create or update PRs

gt stack submit

Motivation: Force pushing branches to GitHub is necessary when you want to update the remote repository with the latest changes. Creating or updating Pull Requests (PRs) ensures that the code changes are reviewed before merging them into the main branch.

Explanation: The stack submit subcommand is used to force push all branches in the current stack to GitHub. This command updates the remote repository with the latest changes from the local branches. It also creates or updates the corresponding Pull Requests (PRs) for each branch, allowing for code review and collaboration.

Example output:

Force pushed all branches to GitHub.
Created or updated PRs for each branch.

Log all tracked stacks

gt log short

Motivation: Logging all tracked stacks provides an overview of the different sequences of dependent code changes and their current status.

Explanation: The log short subcommand is used to display a summarized log of all tracked stacks. This log includes information about the branches and commits in each stack, along with their current status. It helps in keeping track of the progress and status of each code change stack.

Example output:

Stack1:
- Branch1 (Commits: 3, Status: Open)
- Branch2 (Commits: 1, Status: Merged)

Stack2:
- Branch3 (Commits: 2, Status: Open)
- Branch4 (Commits: 1, Status: Draft)

Print help for a specified subcommand

gt subcommand --help

Motivation: When working with gt, it is helpful to have access to detailed information about the available subcommands and their options. Printing help for a specified subcommand provides this information.

Explanation: The subcommand --help syntax can be used to print detailed help for a specified subcommand. Replace subcommand with the actual subcommand for which you need help. This command displays information about the usage, arguments, and options of the specified subcommand.

Example output:

Usage: gt branch create [OPTIONS] BRANCH_NAME

  Create a new branch stacked on top of the current branch and commit staged changes.

Options:
  --help  Show this message and exit.

Conclusion

In this article, we explored various use cases of the gt command, which allows for creating and managing sequences of dependent code changes with Git and GitHub. By understanding how to authenticate, initialize, create branches, commit changes, submit stacks, log stacks, and access help, you can effectively utilize gt to streamline your development process. Remember to refer to the Graphite CLI documentation for more in-depth information and guidance on using gt effectively.