The gtlin command is a custom shell function that streamlines creating git branches from Linear issues. It automatically fetches the Linear issue title and creates a branch using Graphite.
Before setting up gtlin, make sure you have these tools installed:
-
Linear CLI - Install from https://github.com/linearapp/linear or:
npm install -g @linear/cli
-
Graphite CLI - Install from https://graphite.dev/docs/getting-started or:
npm install -g @graphite.dev/gt
- Go to https://linear.app/settings/account/security
- Create a new API key
- Copy the key (it will look like
lin_api_xxxxxxxxxxxxxxxx)
Create the function file in your home directory:
curl -o ~/gtlin-function.sh https://raw.githubusercontent.com/tomgrin10/gtlin/main/gtlin-function.shOr manually create ~/gtlin-function.sh with this content:
#!/bin/bash
# Function to create a git branch from a Linear issue
# Usage: gtlin "HER-123-fix-user-authentication"
gtlin() {
local branch_name="$1"
# Validate input
if [[ -z "$branch_name" ]]; then
echo "Error: Branch name is required"
echo "Usage: gtlin 'HER-xy-name-of-branch'"
return 1
fi
# Check if LINEAR_API_KEY is set
if [[ -z "$LINEAR_API_KEY" ]]; then
echo "Error: LINEAR_API_KEY environment variable is not set"
echo "Please set your Linear API token: export LINEAR_API_KEY='your-token-here'"
return 1
fi
# Extract Linear issue ID from branch name (e.g., HER-123 from HER-123-fix-user-auth)
local issue_id
issue_id=$(echo "$branch_name" | grep -o "^HER-[0-9]\+")
if [[ -z "$issue_id" ]]; then
echo "Error: Branch name must start with HER-xy format (e.g., HER-123-branch-name)"
return 1
fi
echo "Extracting issue ID: $issue_id"
# Get issue title using Linear CLI
local issue_title
issue_title=$(linear issue title "$issue_id" 2>/dev/null)
# Check if Linear CLI command was successful
if [[ $? -ne 0 || -z "$issue_title" ]]; then
echo "Error: Failed to get issue title for $issue_id"
echo "Make sure the issue exists and you have access to it"
return 1
fi
echo "Found Linear issue: $issue_title"
# Run gt create command with the issue title
echo "Creating branch with gt..."
gt create "$branch_name" -m "$issue_title"
if [[ $? -ne 0 ]]; then
echo "Error: gt create command failed"
return 1
fi
# Run gt sr command
echo "Running gt sr..."
gt sr
if [[ $? -ne 0 ]]; then
echo "Warning: gt sr command failed"
return 1
fi
echo "✅ Successfully created branch '$branch_name' with Linear issue title: '$issue_title'"
}
# Export the function so it's available in the shell
export -f gtlinAdd these lines to your shell configuration file:
For zsh (most common on macOS):
echo 'export LINEAR_API_KEY=your_actual_api_key_here' >> ~/.zshrc
echo 'source ~/gtlin-function.sh' >> ~/.zshrcFor bash:
echo 'export LINEAR_API_KEY=your_actual_api_key_here' >> ~/.bashrc
echo 'source ~/gtlin-function.sh' >> ~/.bashrcReplace your_actual_api_key_here with your actual Linear API key!
Either restart your terminal or run:
source ~/.zshrc # for zsh
# or
source ~/.bashrc # for bashTry running:
gtlin --helpYou should see the usage message if everything is set up correctly.
Once set up, you can create branches from Linear issues like this:
gtlin HER-123-add-user-authenticationThis will:
- Extract the issue ID (HER-123) from the branch name
- Fetch the issue title from Linear
- Create a new git branch using Graphite with the Linear issue title as the commit message
- Push the branch and create a PR
Make sure you've added the export line to your shell config file and reloaded it.
Install the Linear CLI: npm install -g @linear/cli
Install Graphite CLI: npm install -g @graphite.dev/gt
- Make sure the Linear issue exists
- Verify you have access to the issue
- Check that your API key is valid
- Validates the branch name format (must start with HER-XXX)
- Extracts the Linear issue ID from the branch name
- Fetches the issue title from Linear using the CLI
- Creates a new git branch using Graphite
- Pushes the branch and creates a pull request automatically
Perfect for maintaining consistency between Linear issues and git branches!