← Back to all cheatsheets
Development
githubgitclighversion-controldevopstransition-guide

GitHub CLI for Git Users

A practical guide for developers who are comfortable with the git CLI and want to learn gh (GitHub CLI).

Table of Contents

The Mental Model

gh is not a replacement for git. It is a companion tool.

If you are coming from git, this is the single most important thing to understand:

ToolOperates OnExamples
gitYour local repository and its remotescommit, branch, merge, rebase, push, pull
ghThe GitHub platformpull requests, issues, releases, actions, gists

git push sends commits up the wire. gh pr create then opens a pull request about those commits on GitHub. Different layers, different jobs.

So when you ask “how do I do git pull with gh?” — the honest answer is: you don’t. You keep using git pull. But gh adds a whole layer of GitHub workflows that git knows nothing about.

”But how do I do git pull with gh?”

This is the question most new gh users ask. Here’s the truth:

# These local git commands have no gh equivalent — keep using git:
git pull                # Pull changes from remote
git push                # Push commits to remote
git status              # Check working tree status
git add                 # Stage changes
git commit              # Create commits
git merge               # Merge branches locally
git rebase              # Rebase commits
git log                 # View commit history
git diff                # See local diffs
git stash               # Stash changes

What gh does is add new capabilities on top of git:

# These have no git equivalent — they only exist on the GitHub layer:
gh pr create            # Open a pull request
gh pr review            # Review code on GitHub
gh issue create         # File an issue
gh run watch            # Watch a GitHub Actions run
gh release create       # Cut a GitHub release

There is some overlap (gh repo clone, gh repo fork), but those are convenience wrappers — the underlying operation is still Git.

Quick Mapping: git → gh

The table below shows things you might want to do, the git way, and the gh addition (if any).

Taskgit commandgh addition
Clone a repogit clone <url>gh repo clone owner/repo (no URL needed)
Pull changesgit pull(no gh equivalent — use git)
Push changesgit push(no gh equivalent — use git)
Create a branchgit checkout -b feature(no gh equivalent — use git)
Commit changesgit commit -m "..."(no gh equivalent — use git)
See remote URLgit remote -vgh repo view
View repo on web(open browser)gh repo view --web
Fork a repo(use GitHub web)gh repo fork owner/repo --clone
Open a PR(use GitHub web)gh pr create
Check out a PRgit fetch origin pull/N/head:pr-Ngh pr checkout N
Merge a PRgit merge (local)gh pr merge N (on GitHub)
See PR diffgit diff main..featuregh pr diff N
List branches with PRs(no easy way)gh pr list
Create an issue(use GitHub web)gh issue create
See CI status(use GitHub web)gh pr checks / gh run list
Create a releasegit tag v1.0 && git push --tagsgh release create v1.0

Setup and Authentication

In git you configure your name, email, and credentials. In gh you log in once and it manages a GitHub token for you.

# git equivalent: git config + credential helper + SSH keys
gh auth login                               # Interactive login (web or token)
gh auth status                              # Show who you're logged in as
gh auth setup-git                           # Wire gh up as a git credential helper
gh auth refresh -s repo,read:org            # Add more OAuth scopes later
gh auth logout

After gh auth setup-git, your normal git push / git clone over HTTPS will use the gh token — no separate PAT in your ~/.netrc or keychain.

Cloning and Forking

# git way
git clone https://github.com/cli/cli.git

# gh way — shorter, no URL needed
gh repo clone cli/cli
gh repo clone cli/cli my-folder             # With a custom directory name

# Forking (git has no equivalent — forking is a GitHub concept)
gh repo fork owner/repo                     # Fork the repo on GitHub
gh repo fork owner/repo --clone             # Fork and clone locally

# From inside an existing clone of the parent repo:
gh repo fork --remote                       # Fork the parent and add the fork as
                                            # a git remote (default name: 'origin';
                                            # existing 'origin' is renamed to 'upstream')
gh repo fork --remote --remote-name myfork  # Use a custom remote name instead

gh repo fork owner/repo --clone clones your new fork and adds the parent as an upstream remote — saving the usual git remote add upstream … step. The --remote flag is different: it is meant to be run from inside an already-cloned parent repo and rewires your remotes so origin points at your fork and upstream points at the parent.

Browsing Repositories

# Open the current repo in your browser
gh repo view --web                          # Like typing the URL by hand

# Show repo metadata in the terminal (description, README, etc.)
gh repo view
gh repo view owner/repo                     # Any repo

# List your repos
gh repo list                                # Your repos
gh repo list orgname --limit 100            # An org's repos

git remote -v tells you the URL; gh repo view --web opens it. They complement each other.

The Pull Request Workflow

This is the workflow where gh shines and where most git users gain the most. Here is the full loop:

# 1. Make your changes locally (pure git)
git checkout -b feature/login-fix
# ... edit files ...
git add .
git commit -m "Fix login redirect bug"
git push -u origin feature/login-fix        # gh did not replace this

# 2. Open the PR (this is where gh takes over)
gh pr create                                # Interactive — prompts for title, body, base
gh pr create --fill                         # Auto-fill from commit messages
gh pr create --title "Fix login" --body "Resolves redirect loop"
gh pr create --draft                        # Open as a draft
gh pr create --web                          # Open the browser PR form instead

# 3. Check on your PR
gh pr status                                # Status of PRs relevant to you
gh pr list --author @me                     # Your open PRs
gh pr view                                  # View the PR for the current branch
gh pr view 123                              # View PR by number
gh pr view --web                            # Open PR in browser

# 4. Iterate
# ... edit files ...
git commit -am "Address review comments"
git push                                    # PR updates automatically — no gh command needed

# 5. Merge
gh pr merge                                 # Interactive merge for current branch's PR
gh pr merge 123 --squash --delete-branch    # One-shot merge & cleanup
gh pr merge 123 --rebase
gh pr merge 123 --auto --squash             # Merge automatically once CI passes

Checking out someone else’s PR

Doing this in plain git is awkward (git fetch origin pull/123/head:pr-123 && git checkout pr-123). With gh:

gh pr checkout 123                          # Fetches and switches to the PR branch

Reviewing Code

There is no git review command. Reviews live on GitHub, so this is pure gh territory:

# See what's changed
gh pr diff 123                              # Like git diff, but for a PR
gh pr diff 123 --patch                      # Patch format

# Submit a review
gh pr review 123 --approve
gh pr review 123 --request-changes --body "Please add tests for the edge case"
gh pr review 123 --comment --body "Looks good — minor nits inline"

# Comment without a formal review
gh pr comment 123 --body "Bumping this — any updates?"

Issues (No Git Equivalent)

Issues do not exist in git at all — they are a GitHub feature. Everything here is new ground if you only know git.

# Find and read issues
gh issue list                               # Open issues in current repo
gh issue list --assignee @me                # Issues assigned to you
gh issue list --label bug --state open
gh issue view 42
gh issue view 42 --web

# File a new issue
gh issue create                             # Interactive
gh issue create --title "Crash on startup" --body "Steps to reproduce..."
gh issue create --label bug --assignee @me

# Work with issues
gh issue comment 42 --body "Reproduced on macOS 14.5"
gh issue close 42 --comment "Fixed in #99"
gh issue reopen 42
gh issue edit 42 --add-label needs-triage

Looking at CI Status

If you find yourself opening the GitHub Actions tab a lot, gh saves you the round trip.

# CI on your current PR
gh pr checks                                # Status of checks for current branch's PR
gh pr checks 123                            # For a specific PR

# All workflow runs
gh run list                                 # Recent runs
gh run list --workflow=ci.yml
gh run list --status=failure --limit 5
gh run view <run-id>                        # Details
gh run view <run-id> --log                  # Full logs
gh run view <run-id> --log-failed           # Only the failed step's logs
gh run watch <run-id>                       # Live tail until completion
gh run rerun <run-id> --failed              # Retry only failed jobs

This is one of the highest-value gh workflows for git users — no more browser tab juggling to check why CI is red.

Releases and Tags

git tag creates a tag locally. A GitHub Release is more than that — it has notes, attached binaries, and a Releases page entry. gh handles the GitHub side:

# Pure git: create and push a tag
git tag -a v1.0.0 -m "Version 1.0.0"
git push origin v1.0.0

# gh: turn that tag into a full Release
gh release create v1.0.0
gh release create v1.0.0 --generate-notes           # Auto-generate from PRs/commits
gh release create v1.0.0 --notes-file CHANGELOG.md
gh release create v1.0.0 ./dist/*.zip ./dist/*.tar.gz   # Attach build artifacts
gh release create v1.0.0 --draft                    # Save as draft
gh release create v1.0.0 --prerelease

# Manage releases
gh release list
gh release view v1.0.0
gh release download v1.0.0                          # Grab the assets
gh release upload v1.0.0 ./new-binary.zip

Working with Forks

The classic “sync my fork with upstream” dance in plain git takes four commands. gh collapses it:

# git way
git fetch upstream
git checkout main
git merge upstream/main
git push origin main

# gh way
gh repo sync                                # Sync your fork's default branch
gh repo sync owner/fork --branch main       # Sync a specific branch
gh repo sync owner/fork --source upstream/repo

Common Combined Workflows

The realistic day-to-day for a git user adopting gh is mixing the two tools fluidly.

Start a feature → push → open PR → merge

git switch main && git pull                 # git: get up to date
git switch -c feature/new-thing             # git: branch
# ... edit ...
git commit -am "Add new thing"              # git: commit
git push -u origin feature/new-thing        # git: push
gh pr create --fill                         # gh:  open the PR
gh pr checks --watch                        # gh:  wait for CI
gh pr merge --squash --delete-branch        # gh:  merge once green
git switch main && git pull                 # git: clean up locally

Triage an incoming PR

gh pr list                                  # gh:  see what's open
gh pr checkout 42                           # gh:  pull it down locally
git log --oneline main..HEAD                # git: see what it adds
gh pr diff 42                               # gh:  or read the diff via gh
# ... test locally ...
gh pr review 42 --approve                   # gh:  approve
gh pr merge 42 --squash --delete-branch     # gh:  merge

Fix a bug that came in via an issue

gh issue view 87                            # gh:  read the bug report
gh issue develop 87 --checkout              # gh:  create + checkout a branch linked to issue #87
# ... fix the bug ...
git commit -am "Fix the bug from #87"       # git: commit
git push -u origin <branch>                 # git: push
gh pr create --fill                         # gh:  PR (auto-links to issue #87)

gh issue develop is a small but lovely command — it creates a branch on GitHub that is associated with the issue, and optionally checks it out for you.

Things gh Does That git Cannot

A reminder of what you gain — none of this exists in plain git:

  • Pull requests: create, list, view, diff, review, comment, merge, check out (gh pr ...)
  • Issues: create, list, view, comment, label, close, link (gh issue ...)
  • GitHub Actions: trigger, watch, view logs, rerun failed jobs (gh run ..., gh workflow ...)
  • Releases: create with notes and assets, edit, delete (gh release ...)
  • Gists: create, list, edit, clone (gh gist ...)
  • Repo admin: create, fork, archive, rename, delete, sync (gh repo ...)
  • GitHub Search: repos, issues, PRs, code, commits (gh search ...)
  • Raw API access: anything REST or GraphQL (gh api ...)

Things to Keep Using git For

gh is not trying to replace these — keep them in your fingers:

  • All staging, committing, and history work: git add, git commit, git log, git blame, git diff, git show
  • All branching and merging on your machine: git branch, git switch, git merge, git rebase, git cherry-pick
  • Talking to remotes at the protocol level: git push, git pull, git fetch, git remote
  • Local-only operations: git stash, git restore, git reset, git worktree
  • Tagging (the tag itself; gh release is what turns a tag into a Release)

A rough rule of thumb: if the action would still make sense on a self-hosted Git server with no GitHub, it is a git command.

Useful Aliases for git Users

If you live in muscle memory like most git users, set up gh aliases that read the way you think:

# Shorten the most-used commands
gh alias set co 'pr checkout'                       # gh co 123
gh alias set prs 'pr list --author @me'             # My open PRs
gh alias set prc 'pr create --fill'                 # Quick PR from current branch
gh alias set prm 'pr merge --squash --delete-branch'
gh alias set ic 'issue create'
gh alias set il 'issue list --assignee @me'

# Inspect CI quickly
gh alias set ci 'pr checks'
gh alias set runs 'run list --limit 10'

# List your work
gh alias set mine 'pr list --author @me --state open'

# List/manage aliases
gh alias list
gh alias delete co

You can also set git aliases that call gh to bridge the two worlds:

git config --global alias.pr '!gh pr create'
git config --global alias.prv '!gh pr view --web'
# Now: git pr   →   opens a pull request
#      git prv  →   opens the current PR in the browser

Resources