appendix ab github desktop

Appendix AB: GitHub Desktop

Episode coming soon: GitHub Desktop - a conversational audio overview of this appendix. Listen before reading to preview the concepts, or after to reinforce what you learned.

A Visual Git Client for Every Workflow

Who this is for: You want a dedicated graphical Git application — something separate from your code editor, with a clear visual interface for cloning, branching, committing, and managing pull requests. GitHub Desktop is a great fit if you prefer working with a purpose-built Git GUI, or if VS Code's Source Control panel feels too embedded in the editor for your workflow.

GitHub Desktop is free, open source, and made by GitHub. It works on Windows and macOS.

---

Table of Contents

1. What GitHub Desktop Does (and Doesn't Do)
2. Installing GitHub Desktop
3. Signing In and Authentication
4. The Interface at a Glance
5. Cloning a Repository
6. Creating and Switching Branches
7. Staging and Committing Changes
8. Push and Pull
9. Syncing Your Fork
10. Resolving Merge Conflicts
11. Viewing History
12. Cherry-Pick in GitHub Desktop
13. Stashing Changes
14. Undoing Changes
15. Accessibility and Screen Reader Notes
16. GitHub Desktop vs VS Code vs Git CLI — When to Use Each

---

1. What GitHub Desktop Does (and Doesn't Do)

GitHub Desktop covers the everyday Git workflow that most contributors use on most days.

What it supports

• ✅ Clone repositories from GitHub
• ✅ Create, switch, and delete branches
• ✅ Stage files (and individual lines/hunks within files)
• ✅ Write commit messages and commit
• ✅ Push and pull from GitHub
• ✅ Open pull requests (launches GitHub.com in your browser)
• ✅ Resolve merge conflicts with a visual editor
• ✅ View commit history and diffs
• ✅ Cherry-pick commits between branches
• ✅ Stash and restore uncommitted changes
• ✅ Undo commits and discard changes

What it does not support (use Git CLI or VS Code terminal instead)

• ❌ Interactive rebase (git rebase -i)
• ❌ git bisect
• ❌ git clean
• ❌ Creating annotated tags
• ❌ Commit signing (GPG/SSH)

For these operations, open the repository in your terminal directly from GitHub Desktop — Repository → Open in Terminal or Repository → Open in Command Prompt puts you in the right directory instantly.

---

2. Installing GitHub Desktop

Windows

Option A: Winget (recommended)

winget install GitHub.GitHubDesktop

Option B: Direct download

1. Go to desktop.github.com
2. Select "Download for Windows"
3. Run the installer — it installs and launches automatically

macOS

Option A: Homebrew

brew install --cask github

Option B: Direct download

1. Go to desktop.github.com
2. Select "Download for macOS"
3. Open the downloaded .zip, drag GitHub Desktop to your Applications folder

Linux: GitHub Desktop does not officially support Linux. Linux users should use VS Code's Source Control panel or the Git CLI.

---

3. Signing In and Authentication

GitHub Desktop uses browser-based OAuth sign-in — no tokens or SSH keys needed. It handles authentication for you automatically.

Sign in on first launch

1. Open GitHub Desktop
2. Select "Sign in to GitHub.com"
3. Your browser opens to a GitHub authorization page — sign in with your GitHub account
4. Authorize GitHub Desktop when prompted
5. Switch back to GitHub Desktop — you're signed in

That's it. GitHub Desktop stores your credentials securely in the system keychain. You won't be asked for a password again.

If you use GitHub Enterprise or a GitHub organization: Select "Sign in to GitHub Enterprise Server" and enter your organization's server URL.

---

4. The Interface at a Glance

GitHub Desktop has three main areas:

┌─────────────────────────────────────────────────────────┐
│  Toolbar: Current Repository ▾  |  Current Branch ▾  |  │
│                                    Fetch/Push button      │
├─────────────────┬───────────────────────────────────────┤
│                 │                                         │
│  Left panel:    │  Main area:                            │
│  Changes tab    │  File diff view                        │
│  (staged /      │  (what changed in the selected file)   │
│  unstaged)      │                                        │
│                 │                                         │
│  OR             │                                         │
│                 │                                         │
│  History tab    │  Commit detail / diff                  │
│  (past commits) │                                        │
│                 │                                         │
├─────────────────┴───────────────────────────────────────┤
│  Commit area: Summary field | Description | Commit button │
└─────────────────────────────────────────────────────────┘

Key controls

Element	What it does
Current Repository (top left)	Switch between your cloned repos
Current Branch (top middle)	Switch branches, create new branches
Fetch/Push button (top right)	Sync with GitHub (fetch, push, pull)
Changes tab	Shows your uncommitted changes
History tab	Shows your commit history
Summary field (bottom left)	Where you type your commit message
Commit button (bottom left)	Commits staged changes

---

5. Cloning a Repository

From GitHub.com

The easiest way is to go to the repository on GitHub.com and use the Code button:

1. On the repository page, activate Code → Open with GitHub Desktop
2. GitHub Desktop opens with a dialog confirming the URL
3. Choose where to save the repository on your computer
4. Select "Clone"

From inside GitHub Desktop

1. Press Ctrl+Shift+O (Windows) or Cmd+Shift+O (macOS) — "Clone a repository"
2. Choose the GitHub.com tab to browse your own repositories, or the URL tab to paste any repo URL
3. Select or type the repository
4. Choose a local path
5. Select "Clone"

GitHub CLI alternative

gh repo clone owner/repo-name
# Then open it in GitHub Desktop:
github /path/to/repo

---

6. Creating and Switching Branches

Create a new branch

1. Click Current Branch in the toolbar (or press Ctrl+Shift+N / Cmd+Shift+N)
2. Type a name for your new branch
3. Select "Create Branch"
4. Choose whether to base it on the current branch or another — usually keep the default

GitHub Desktop switches to the new branch immediately.

Switch to an existing branch

1. Click Current Branch in the toolbar
2. Type to search or scroll through the branch list
3. Click the branch name — GitHub Desktop switches and updates your files

Delete a branch

1. Click Current Branch in the toolbar
2. Right-click the branch you want to delete
3. Select "Delete..."

Screen reader tip: The branch selector is a dropdown that opens a searchable list. Screen readers announce the currently selected branch name in the toolbar. After switching, the branch name in the toolbar updates to confirm the switch.

---

7. Staging and Committing Changes

Reviewing your changes

When you edit files in your editor and save them, GitHub Desktop automatically detects the changes and shows them in the Changes tab on the left.

• The left panel lists every changed file with a checkbox
• The right panel shows the diff for the selected file — red lines removed, green lines added

Staging files

Every file with a checked checkbox will be included in your next commit.

• Check all — click the checkbox at the top of the list to stage everything
• Uncheck a file to exclude it from the commit (it stays as an uncommitted change)

Staging individual lines (hunks)

If a file has multiple changes and you only want to commit some of them:

1. Select the file in the Changes list
2. In the diff view, right-click a line or block
3. Select "Stage Line" or "Stage Hunk" — only those lines get included in the commit

Writing your commit message

1. In the Summary field at the bottom, type a short commit message (under 72 characters is ideal)
2. Optionally add a longer description in the Description field below it
3. Select "Commit to [branch name]" — your changes are committed locally

GitHub Copilot can help: Not sure what to write? Open VS Code alongside GitHub Desktop, open Copilot Chat, and ask: "Write a commit message for these changes: [describe what you changed]." Or use the conventional commit format: feat:, fix:, docs:, refactor:.

Screen reader tip (Windows, NVDA/JAWS): The Summary and Description fields are standard text inputs — navigate to them with Tab and type normally. The commit button is announced as a button labelled "Commit to [branch name]."

---

8. Push and Pull

After committing, your changes are saved locally but not yet on GitHub. The Fetch/Push button in the top-right toolbar handles syncing.

Pushing commits to GitHub

After committing, the button changes to "Push origin" with an upward arrow and the number of commits waiting.

• Click "Push origin" — your commits go to GitHub

Pulling changes from GitHub

When collaborators have pushed new commits, the button shows "Pull origin" with a downward arrow.

• Click "Pull origin" — GitHub Desktop downloads the new commits and updates your local branch

Fetching (checking without pulling)

• Click "Fetch origin" — GitHub Desktop checks for new commits and shows you the count, but doesn't update your files yet
• This is safe to do at any time — it's read-only

Keyboard shortcuts

Action	Windows	macOS
Push / Pull / Fetch	Ctrl+P	Cmd+P

---

9. Syncing Your Fork

If you forked a repository and the original upstream repo has new commits you want to bring in:

1. Go to Branch → Merge into current branch...
2. In the branch picker, switch to the "Other branches" tab
3. Select upstream/main (or upstream/master) — the upstream remote's default branch
4. Select "Create a merge commit"
5. Then push to your fork with "Push origin"

Setting up the upstream remote (if not already there)

GitHub Desktop adds the upstream remote automatically when you clone a fork from GitHub.com. If it's missing:

1. Open the repository in terminal: Repository → Open in Terminal
2. Run:

git remote add upstream https://github.com/ORIGINAL-OWNER/ORIGINAL-REPO.git
git fetch upstream

3. Switch back to GitHub Desktop — it will now see the upstream branches

---

10. Resolving Merge Conflicts

When you pull from GitHub or merge a branch and there are conflicts, GitHub Desktop shows a dialog listing the conflicting files.

Step by step

1. GitHub Desktop shows a "Resolve conflicts before merging" screen

2. Each conflicting file has two options next to it:

   • "Open in [your editor]" — opens the file with conflict markers for manual editing
   • "Use mine" / "Use theirs" — accept one entire side of the conflict without editing

3. For simple conflicts (one side is clearly right), use "Use mine" or "Use theirs"

4. For conflicts where you need to keep parts of both, select "Open in [editor]" and resolve manually

After resolving in your editor

1. Save the file
2. Switch back to GitHub Desktop — the file moves from "Conflicting" to "Resolved"
3. Once all conflicts are resolved, select "Continue merge"

GitHub Copilot can help: Open the conflicting file in VS Code alongside GitHub Desktop. Place your cursor inside a conflict region and open Copilot Chat (Ctrl+Shift+I): "Resolve this merge conflict — keep meaningful changes from both sides." Copilot suggests a resolution; you review and save.

Screen reader tip: The conflicts dialog lists files as a navigable list. Each file entry includes the action buttons ("Open in editor", "Use mine", "Use theirs"). Navigate with Tab between the file entries and buttons.

---

11. Viewing History

The History tab (next to the Changes tab in the left panel) shows every commit on the current branch.

Navigating history

1. Click the History tab
2. Each commit appears as a row: author avatar, commit message, author name, and timestamp
3. Click any commit to see the full diff on the right — what changed in each file

Filtering commits

Type in the search field above the commit list to filter by commit message, author, or SHA.

Viewing a specific file's history

1. Right-click any file in your project (via the Files panel in the diff area)
2. Select "Show in History" — the commit list filters to only commits that touched that file

Comparing branches

1. Click History
2. In the branch comparison bar above the commit list, switch to another branch
3. GitHub Desktop shows the commits that are different between your current branch and the selected branch

---

12. Cherry-Pick in GitHub Desktop

Cherry-pick lets you take a commit from another branch and apply it to your current branch — without merging the whole branch.

How to cherry-pick

1. Switch to the branch you want to copy the commit FROM (the source branch)
2. Open the History tab
3. Find the commit you want to copy
4. Right-click the commit
5. Select "Cherry-pick commit..."
6. Choose the destination branch — the branch you want to apply the commit TO
7. GitHub Desktop applies the commit and switches to the destination branch

If there's a conflict

GitHub Desktop shows the conflict resolution screen (same as merging). Resolve the conflicts in your editor, then switch back to GitHub Desktop to continue.

GitHub Copilot can help: Before cherry-picking, open Copilot Chat and paste the commit diff: "What does this commit do? Is it safe to cherry-pick onto a branch that doesn't have the surrounding context?"

---

13. Stashing Changes

Stash saves your uncommitted changes temporarily so you can switch branches or pull without committing half-finished work.

Stash your changes

1. Go to Branch → Stash All Changes (or press Ctrl+Shift+H / Cmd+Shift+H)
2. Your working directory reverts to the last commit
3. You can now switch branches safely

Restore your stash

1. Switch back to the branch where you stashed
2. Go to Branch → Pop Stash
3. Your changes come back

Note: GitHub Desktop supports one stash at a time per branch. For multiple stashes, use the Git CLI: git stash list, git stash apply stash@{1}. See Chapter 11, Section 10 for the full stash guide.

---

14. Undoing Changes

Undo the last commit

Go to Edit → Undo Last Commit (or press Ctrl+Z / Cmd+Z right after committing)

This is equivalent to git reset --soft HEAD~1 — your changes come back as staged files. Nothing is lost.

Discard changes to a file

In the Changes tab:

1. Right-click a file
2. Select "Discard Changes..."
3. Confirm the dialog — the file reverts to its last committed state

Warning: Discarding changes cannot be undone. The changes are permanently deleted, not moved to trash.

Discard all changes

1. Right-click anywhere in the Changes list
2. Select "Discard All Changes..."
3. Confirm — everything in your working directory reverts to the last commit

---

15. Accessibility and Screen Reader Notes

GitHub Desktop has partial screen reader support. Core workflows work well with keyboard navigation; some visual-only elements (like avatar images and some icons) don't have text equivalents.

What works well

Feature	Accessibility notes
Commit message fields	Standard text inputs, fully accessible
Branch selector	Searchable dropdown, keyboard navigable
File list (Changes/History)	Arrow keys to navigate, checkboxes announceable
Commit button	Labelled with branch name, activatable with Enter
Conflict resolution dialog	Buttons ("Use mine", "Use theirs") are labelled
Keyboard shortcut access	Most operations have keyboard shortcuts

What has limitations

Feature	Limitation
Diff view	The colored diff panel is partially accessible; individual lines may not be announced clearly on all platforms. Workaround: Open in VS Code for better diff navigation
File icons	Status icons (M for modified, A for added, D for deleted) may not always be announced — the filename is still readable
Context menus	Right-click context menus work via keyboard (Shift+F10 on Windows; Ctrl+Click on macOS)

Windows — NVDA / JAWS

• Use Tab to move between panels; arrow keys within lists
• The commit summary field is reached with Tab after the file list
• Conflict dialogs are modal — screen reader focus moves into the dialog automatically

macOS — VoiceOver

• Use Tab and VO+Arrow to navigate panels
• The diff view can be explored with VO+Right through the lines
• Branch selector opens a searchable popup — type to filter, Down Arrow to navigate, Return to select

VS Code as a better accessible alternative

If screen reader navigation in GitHub Desktop is frustrating for a specific operation, VS Code's Source Control panel is often more accessible. The two tools complement each other — use whichever works best for the task at hand.

---

16. GitHub Desktop vs VS Code vs Git CLI — When to Use Each

Situation	Best tool
You want a clean visual overview of changes before committing	GitHub Desktop
You want to stage individual lines or hunks	GitHub Desktop or VS Code
You're doing complex operations (rebase, bisect, clean)	Git CLI (terminal)
You want the fastest screen-reader-friendly experience	Git CLI or VS Code terminal
You want to open a PR or manage issues without leaving your tool	VS Code (GitHub Pull Requests extension)
You want to manage multiple repos at once with a visual switcher	GitHub Desktop
You're doing quick commits mid-coding session	VS Code (Source Control panel — already open)

GitHub Desktop, VS Code, and the Git CLI all talk to the same Git repository. You can switch between them freely — use GitHub Desktop to stage and commit, then open the terminal for a git rebase -i. They don't conflict.

---

Related chapters and appendices: Chapter 11: Git & Source Control in VS Code · Appendix AA: Advanced Git Operations · Appendix D: Git Authentication · Chapter 12: GitHub Pull Requests Extension