Git Pull Request Workflow with GitHub CLI

git_pull-request-workflow.md

Git Pull Request Workflow with GitHub CLI

This document explains how to properly manage pull requests using GitHub CLI.

The examples provided use main as the default branch. Replace it with master or another default branch name when applicable.

Install GitHub CLI

# Install via Homebrew
brew install gh

# Authenticate
gh auth login

# Check authentication status
gh auth status

# Check broader status
gh status

Create a new branch

# Switch to main and fast forward
git switch main
git pull --ff-only

# Create the branch
git switch -c docs/update-readme

Do some work

# Do some work

# Inspect modifications
git status
git diff

# Stage and commit
git add README.md
git commit -m "Update installation instructions"

Push the Branch and Create a Pull Request

# Push your changes (after they are committed)
git push -u origin docs/update-readme

# Populate the PR title and body from commit information
gh pr create --fill

# Or fill it yourself
gh pr create \
  --base main \
  --title "Update installation instructions" \
  --body "Clarifies the installation steps in the README."

Review the Pull Request

This would be done by the person in charge, or yourself for single maintainer repos.

# View the PR
gh pr view

# Inspect changes
gh pr diff

# View checks
gh pr checks

Merge the Pull Request

If you want to preserve the individual commits while producing a linear history, use rebase. This recreates the commits with new hashes while retaining their messages and authorship information.

# Or merge with rebase
gh pr merge --rebase --delete-branch

If you don't want the detailed commit history of the branch and want to combine all PR changes into one new commit.

# Merge and Squash commits
gh pr merge --squash --delete-branch

If you want to preserve the branch structure and record an explicit merge commit (This produces a non-linear history and is unavailable when the repository requires a linear history).

# Or Merge keeping commits
gh pr merge --merge --delete-branch

Going back to your main branch

git switch main
git pull --ff-only

If you didn't delete the branch and want to remove it later

# Delete remote branch
git push origin --delete docs/update-readme

# Delete local branch
git branch -d docs/update-readme

# Prune
git fetch --prune

Note: git branch -d may refuse to delete a branch after a rebase or squash merge because the original commits are not ancestors of main. You can check if the PR is indeed applied by:

# Update your local view of the remote
git fetch --prune

# Return to an up-to-date main branch
git switch main
git pull --ff-only

# Confirm that the pull request was merged
gh pr view docs/update-readme

# Check for commits whose equivalent changes are absent from main
git cherry main docs/update-readme
# Lines beginning with - have equivalent changes on main.
# Lines beginning with + may contain changes not found on main.

# Delete the remote branch, if it still exists
git push origin --delete docs/update-readme

# Delete the local branch
git branch -D docs/update-readme

# Remove stale remote-tracking references
git fetch --prune