How to Create Pull Requests from your Terminal

Pull requests (PRs) are fundamental to collaborative development on GitHub, enabling code review and discussion before changes are merged. This guide explains how to create and manage PRs efficiently using the terminal, primarily using GitHub CLI (gh).

Prerequisites

Before starting, ensure you have:

• Git installed and configured (Download Git)
• GitHub CLI (gh) installed (GitHub CLI docs)
• A GitHub account (Sign up)
• Repository access and necessary permissions
• Basic understanding of Git commands

Setting Up GitHub CLI

Installation

Choose your operating system:

macOS

# Using Homebrew
brew install gh

# Using MacPorts
sudo port install gh

Linux

# Debian/Ubuntu
curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
echo ""deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main"" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null
sudo apt update
sudo apt install gh

# Fedora
sudo dnf install gh

# Arch Linux
sudo pacman -S github-cli

Windows

# Using Scoop
scoop install gh

# Using Winget
winget install --id GitHub.cli

Authentication

After installation, authenticate with GitHub:

gh auth login

Follow the interactive prompts to complete authentication. You can choose between HTTPS or SSH protocols.

Creating a Pull Request

1. Prepare Your Branch

# Update your local main branch
git checkout main
git pull origin main

# Create and switch to a new feature branch
git checkout -b feature/your-feature-name

2. Make and Commit Changes

# Stage all changes
git add .

# Create a commit with a descriptive message
git commit -m ""feat: implement new feature

- Added new functionality
- Updated documentation
- Fixed related issues""

3. Push Changes

# Push your branch to GitHub
git push -u origin feature/your-feature-name

4. Create the Pull Request

Using GitHub CLI (Recommended)

Basic PR Creation

gh pr create --title ""Feature: Implement New Functionality"" --body ""Description of changes""

Advanced PR Creation

gh pr create 
  --title ""Feature: Implement New Functionality"" 
  --body ""## Changes
- Implemented new feature
- Updated tests
- Added documentation

## Related Issues
Closes #123"" 
  --base main 
  --head feature/your-feature-name 
  --reviewer username1,username2 
  --label ""enhancement,documentation"" 
  --milestone ""v1.0.0"" 
  --project ""Project Board""

5. Managing Your PR

# View PR in browser
gh pr view --web

# Check PR status
gh pr status

# List all PRs
gh pr list

# Add reviewers to existing PR
gh pr edit --add-reviewer username1,username2

# Add labels
gh pr edit --add-label ""priority,bug""

Best Practices

1. Branch Naming
   • Use descriptive prefixes: feature/, fix/, docs/, refactor/
   • Include issue number if applicable: feature/123-user-authentication
2. Commit Messages
   • Follow conventional commits (Convention)
   • Include scope and description
   • Reference issues: ""fixes #123""
3. PR Description
   • Use templates if available
   • Include context and reasoning
   • List related issues and dependencies
   • Add screenshots for UI changes
4. Code Review
   • Respond to feedback promptly
   • Update PR description as needed
   • Resolve conflicts quickly

Troubleshooting

Common Issues and Solutions

1. Authentication Failed

   gh auth login --web
   

2. Push Rejected

   git pull origin main
   git rebase main
   git push -f origin feature/your-feature-name
   

3. Merge Conflicts

   git checkout main
   git pull
   git checkout feature/your-feature-name
   git rebase main
   # Resolve conflicts and continue
   git rebase --continue
   

Advanced Features

Draft PRs

gh pr create --draft

PR Templates

Create .github/pull_request_template.md in your repository for standardized PR descriptions.

Automating PR Creation

You can create shell aliases or scripts for common PR patterns:

# Add to .bashrc or .zshrc
alias pr-create='gh pr create --template ""template.md"" --label ""needs-review""'

Remember to keep your GitHub CLI updated for the latest features:

# Update GitHub CLI
gh update

FAQs

[TOGGLE question=""What do I do if authentication fails?"" answer=""Use gh auth login --web to authenticate through your browser instead of the terminal interface.""]

[TOGGLE question=""How do I handle rejected pushes?"" answer=""1. Pull the latest changes: git pull origin mainn2. Rebase your branch: git rebase mainn3. Force push: git push -f origin feature/your-feature-name""]

[TOGGLE question=""How do I resolve merge conflicts?"" answer=""1. Checkout main: git checkout mainn2. Pull latest changes: git pulln3. Switch to your branch: git checkout feature/your-feature-namen4. Rebase: git rebase mainn5. Resolve conflicts and continue: git rebase --continue""]

[TOGGLE question=""Can I create draft PRs?"" answer=""Yes, use the --draft flag: gh pr create --draft""]

[TOGGLE question=""How do I use PR templates?"" answer=""Create a .github/pull_request_template.md file in your repository for standardized PR descriptions.""] [Previous content remains exactly the same until the Useful Resources section]

Conclusion

Mastering the terminal-based approach to creating and managing pull requests can significantly enhance your development workflow. GitHub CLI (gh) provides a powerful set of tools that streamline the PR process, from creation to merge. By following the best practices outlined in this guide and utilizing GitHub CLI’s features, you can:

• Save time by avoiding context switches between terminal and browser
• Maintain consistent PR quality through templates and conventions
• Handle common PR challenges efficiently
• Automate repetitive PR-related tasks