mauvehed.com
mauvehed's dotfiles for personal and work environments
1# GitHub Usage
2
3This document provides guidance on interacting with GitHub, primarily focusing on the GitHub CLI tool (`gh`) and general best practices.
4
5## Overview
6
7GitHub 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.
8
9## GitHub CLI (`gh`)
10
11The GitHub CLI is the preferred way to interact with GitHub programmatically and from the terminal for many tasks.
12
13### Installation
14
15The GitHub CLI is typically installed via Homebrew if specified in your `chezmoi` configurations:
16```sh
17brew install gh
18```
19Refer to the [official installation guide](https://github.com/cli/cli#installation) for other methods.
20
21### Authentication
22
23After installation, you need to authenticate `gh` with your GitHub account:
24```sh
25gh auth login
26```
27Follow the prompts. Using `HTTPS` and authenticating with web browser is often the easiest method.
28
29### Common `gh` Commands
30
31* **Repository Commands (`gh repo ...`)**
32 * Clone a repository:
33 ```sh
34 gh repo clone <owner>/<repository_name>
35 # Example: gh repo clone cli/cli
36 ```
37 * Create a new repository:
38 ```sh
39 gh repo create <repository_name> [options]
40 # Example: gh repo create my-new-project --public --source=.
41 ```
42 * View a repository in the browser:
43 ```sh
44 gh repo view --web
45 ```
46
47* **Pull Request Commands (`gh pr ...`)**
48 * List pull requests:
49 ```sh
50 gh pr list
51 ```
52 * View a specific pull request:
53 ```sh
54 gh pr view <pr_number_or_branch_name>
55 # View in browser: gh pr view <pr_number_or_branch_name> --web
56 ```
57 * Checkout a pull request locally:
58 ```sh
59 gh pr checkout <pr_number_or_branch_name>
60 ```
61 * Create a pull request:
62 ```sh
63 gh pr create [options]
64 # Example (prompts for title, body, base branch, etc.):
65 # gh pr create
66 # Example (with details):
67 # gh pr create --title "My Awesome Feature" --body "Details about the feature." --base main
68 ```
69 * Diff a pull request:
70 ```sh
71 gh pr diff <pr_number_or_branch_name>
72 ```
73
74* **Issue Commands (`gh issue ...`)**
75 * List issues:
76 ```sh
77 gh issue list
78 ```
79 * View an issue:
80 ```sh
81 gh issue view <issue_number>
82 # View in browser: gh issue view <issue_number> --web
83 ```
84 * Create an issue:
85 ```sh
86 gh issue create --title "My Issue Title" --body "Issue details."
87 ```
88
89* **Alias Management (`gh alias ...`)**
90 * `gh` supports creating aliases for complex commands. Example:
91 ```sh
92 gh alias set myprs "pr list --author @me"
93 gh myprs # Runs the aliased command
94 ```
95
96## Git Configuration for GitHub
97
98Ensure 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.
99
100SSH 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](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent) and [adding it to your GitHub account](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account).
101
102## Resources
103
104* **GitHub CLI Official Documentation**: [https://cli.github.com/manual/](https://cli.github.com/manual/)
105* **GitHub CLI GitHub Repository**: [https://github.com/cli/cli](https://github.com/cli/cli)
106* **GitHub Help Documentation**: [https://docs.github.com/](https://docs.github.com/)
107* **GitHub SSH Key Setup**: [Connecting to GitHub with SSH](https://docs.github.com/en/authentication/connecting-to-github-with-ssh)
108
109This document provides a basic overview. The GitHub CLI is very powerful; explore its manual for more commands and options.