GitHub Usage#

This document provides guidance on interacting with GitHub, primarily focusing on the GitHub CLI tool (gh) and general best practices.

Overview#

GitHub is a platform for version control and collaboration using Git. The GitHub CLI (gh) brings GitHub to your terminal, allowing you to manage repositories, pull requests, issues, and more without leaving the command line.

GitHub CLI (`gh`)#

The GitHub CLI is the preferred way to interact with GitHub programmatically and from the terminal for many tasks.

Installation#

The GitHub CLI is typically installed via Homebrew if specified in your chezmoi configurations:

brew install gh

Refer to the official installation guide for other methods.

Authentication#

After installation, you need to authenticate gh with your GitHub account:

gh auth login

Follow the prompts. Using HTTPS and authenticating with web browser is often the easiest method.

Common `gh` Commands#

Repository Commands (gh repo ...)

Clone a repository:

gh repo clone <owner>/<repository_name>
# Example: gh repo clone cli/cli

Create a new repository:

gh repo create <repository_name> [options]
# Example: gh repo create my-new-project --public --source=.

View a repository in the browser:
```
gh repo view --web
```

Pull Request Commands (gh pr ...)

List pull requests:
```
gh pr list
```

View a specific pull request:

gh pr view <pr_number_or_branch_name>
# View in browser: gh pr view <pr_number_or_branch_name> --web

Checkout a pull request locally:

gh pr checkout <pr_number_or_branch_name>

Create a pull request:

gh pr create [options]
# Example (prompts for title, body, base branch, etc.):
# gh pr create
# Example (with details):
# gh pr create --title "My Awesome Feature" --body "Details about the feature." --base main

Diff a pull request:
```
gh pr diff <pr_number_or_branch_name>
```

Issue Commands (gh issue ...)

List issues:
```
gh issue list
```

View an issue:

gh issue view <issue_number>
# View in browser: gh issue view <issue_number> --web

Create an issue:

gh issue create --title "My Issue Title" --body "Issue details."

Alias Management (gh alias ...)
- gh supports creating aliases for complex commands. Example:
```
gh alias set myprs "pr list --author @me"
gh myprs # Runs the aliased command
```

Git Configuration for GitHub#

Ensure your local Git configuration (see docs/git-usage.md) is set up correctly with your GitHub username and email, especially if you contribute to multiple repositories or use different identities.

SSH keys are recommended for git push/pull operations with GitHub for better security and convenience. Refer to GitHub's documentation on generating a new SSH key and adding it to your GitHub account.

Resources#

GitHub CLI Official Documentation: https://cli.github.com/manual/
GitHub CLI GitHub Repository: https://github.com/cli/cli
GitHub Help Documentation: https://docs.github.com/
GitHub SSH Key Setup: Connecting to GitHub with SSH

This document provides a basic overview. The GitHub CLI is very powerful; explore its manual for more commands and options.