Preferences - GitHub Desktop

Overview

GitHub Desktop provides comprehensive preferences to customize the app’s behavior, appearance, and integrations to match your workflow.

Appearance

Choose themes and customize the UI

Git Configuration

Set your Git identity and default settings

Integrations

Connect external editors and terminal apps

Advanced Options

Configure proxy, SSH, and advanced Git settings

Accessing Preferences

Windows/Linux
macOS

File > Options > Preferences
Or press Ctrl+,

GitHub Desktop > Preferences
Or press Cmd+,

Accounts

GitHub and GitHub Enterprise

Manage your connected accounts:

Open Accounts Tab

Click the Accounts tab in Preferences

GitHub.com: Sign in with your GitHub account
GitHub Enterprise Server: Add your enterprise server URL

Authorize

Complete OAuth authorization in your browser

Multiple Accounts

You can connect both GitHub.com and Enterprise accounts

What You Can Do:

Clone repositories you have access to
Create pull requests
View CI/CD status
Access organization repositories

Sign Out:

Click Sign out next to the account
Removes OAuth token
Clears account access

Appearance

Theme Selection

Light
Dark
System

Bright theme optimized for daylight viewing:

High contrast
Easy to read in bright environments
Traditional appearance

Application Theme Implementation

// From app/src/ui/lib/application-theme.ts
export enum ApplicationTheme {
  Light = 'light',
  Dark = 'dark',
  System = 'system',
}

export type ApplicableTheme = 'light' | 'dark'

// Determines which theme to apply
function getApplicableTheme(
  theme: ApplicationTheme,
  systemTheme: ApplicableTheme
): ApplicableTheme {
  if (theme === ApplicationTheme.System) {
    return systemTheme
  }
  return theme === ApplicationTheme.Light ? 'light' : 'dark'
}

Git Configuration

User Identity

Set your name and email for commits:

Open Git Tab

Click the Git tab in Preferences

Enter Name

Your full name (appears in commit history)

Enter Email

Email address (used for commit attribution)

Save

Changes apply to all new repositories

These settings configure your global Git identity using git config --global user.name and git config --global user.email.

Per-Repository Configuration:

Right-click repository > Repository Settings
Override global settings for specific repositories
Useful for work vs. personal projects

Default Branch Name

Set the name for new repository default branches:

main (GitHub standard)
master (traditional default)
Custom name of your choice

This configures git config --global init.defaultBranch.

Commit Behavior

Amend Last Commit

Enable quick amending of the most recent commit:

Shows checkbox in commit message area
Allows adding files to last commit
Can edit commit message

Never amend commits that have been pushed to shared branches.

GPG Signing

Sign commits with GPG keys:

Requires GPG setup on your system
Configure key in Git config
Adds verification to commits

Setup:

git config --global user.signingkey <key-id>
git config --global commit.gpgsign true

Line Ending Conversion

How Git handles line endings:

Windows: core.autocrlf = true
macOS/Linux: core.autocrlf = input

Prevents cross-platform line ending issues.

Integrations

External Editor

Set your preferred code editor: Supported Editors:

Visual Studio Code
Visual Studio Code - Insiders
Atom
Sublime Text
Visual Studio
Notepad++
TextMate (macOS)
Brackets
Typora
SlickEdit
IntelliJ IDEA
WebStorm
PhpStorm
PyCharm
RubyMine
GoLand
Rider
Android Studio
Nova (macOS)

Open Integrations Tab

Click Integrations in Preferences

Select Editor

Choose your editor from the dropdown

Install if Needed

GitHub Desktop auto-detects installed editors

Usage:

Click Repository > Open in [Editor]
Or press Ctrl+Shift+A (Windows/Linux) / Cmd+Shift+A (macOS)
Right-click files > Open in [Editor]

Terminal/Shell

Set your preferred terminal application: Built-in Options:

Windows
macOS
Linux

Command Prompt
PowerShell
PowerShell Core
Git Bash
Windows Terminal

Custom Shell: You can configure a custom shell executable if your preferred terminal isn’t listed. Usage:

Click Repository > Open in Terminal
Or press Ctrl+` (Windows/Linux) / Cmd+` (macOS)
Terminal opens in repository directory

Shell Configuration

GitHub Desktop can be configured to use a specific shell:

# Set custom shell (example)
gh config set shell /bin/zsh

Shell integration provides:

Repository path automatically set
Git environment configured
Immediate access to git commands

Advanced Settings

Proxy Configuration

GitHub Desktop automatically detects system proxy settings, but you can configure manually:

Open Advanced Tab

Click Advanced in Preferences

Configure Proxy

GitHub Desktop uses system proxy by default
For manual config, set environment variables
Or configure in Git: git config --global http.proxy

See Proxies for detailed information.

Repository Storage Location

Set default directory for cloned repositories:

Click Change next to “Default clone directory”
Select a folder on your computer
Future clones default to this location
Can be overridden per-clone

Choose a location that’s:

Easy to find
Has adequate storage
Is regularly backed up
Not in cloud sync folders (Dropbox, OneDrive)

Confirmation Dialogs

Control which confirmation dialogs appear:

Force Push Warning

Show confirmation dialog before force pushing (Recommended)When enabled:

Warns about force push impact
Explains history rewriting
Asks for confirmation

When disabled:

Force push happens immediately
Higher risk of mistakes

Discard Changes Warning

Show confirmation dialog before discarding changesWhen enabled:

Warns that changes cannot be recovered
Lists files that will be discarded
Requires confirmation

When disabled:

Discard happens immediately
Easy to lose work accidentally

Large File Warning

Show warning when committing large filesWhen enabled:

Warns about files over 50MB
Suggests using Git LFS
Asks for confirmation

When disabled:

Large files committed without warning
Can bloat repository

Background Operations

Automatic Fetch

Periodically fetch from remotesWhen enabled:

Fetches every few minutes
Keeps remote tracking branches updated
Shows new commits and PRs

When disabled:

Must manually fetch
Remote info may be stale

Interval: Configurable (default: 3 minutes)

Prune on Fetch

Prune remote branches on fetchWhen enabled:

Removes remote-tracking branches that no longer exist
Keeps branch list clean
Equivalent to git fetch --prune

When disabled:

Deleted remote branches remain in list
Must manually prune

Diff Display

Configure how diffs are shown:

Context lines: Number of unchanged lines around changes
Whitespace: How to handle whitespace differences
- Show all changes
- Ignore whitespace at end of lines
- Ignore all whitespace changes
Word diff: Highlight changed words, not just lines
Syntax highlighting: Enable/disable code highlighting

Experimental Features

Enable beta features:

Experimental features may be unstable or change without notice. Use with caution in production workflows.

Examples:

New UI components
Enhanced diff algorithms
Experimental Git features
Beta integrations

Check GitHub Desktop release notes for available experiments.

Preference Storage

Preferences are stored locally:

Configuration Files

Windows
macOS
Linux

%APPDATA%\GitHub Desktop\

Settings stored in JSON and SQLite databases.

~/Library/Application Support/GitHub Desktop/

Settings use macOS user defaults and JSON files.

~/.config/GitHub Desktop/

Settings stored in JSON configuration files.

App State

GitHub Desktop stores:

Repository list
Window size/position
Selected repository
Recent file selections
UI state (expanded sections, etc.)

Resetting Preferences

To reset all settings:

Quit GitHub Desktop
Delete the configuration directory
Restart GitHub Desktop
Reconfigure preferences

Resetting preferences removes all settings and account connections. You’ll need to sign in again and reconfigure everything.

Keyboard Shortcuts

General

Action	Windows/Linux	macOS
Preferences	`Ctrl+,`	`Cmd+,`
Hide window	`Ctrl+W`	`Cmd+W`
Quit	`Ctrl+Q`	`Cmd+Q`
Toggle full screen	`F11`	`Ctrl+Cmd+F`

View Shortcuts

Configure additional keyboard shortcuts in Preferences > Shortcuts (if available in your version).

Best Practices

Keep your email address private: GitHub offers a no-reply email address (e.g., [email protected]) to keep your personal email private.

Use Consistent Identity
- Same name/email across all repositories
- Helps with commit attribution
- Easier to track contributions
Enable Confirmations
- Keep dangerous action warnings on
- Prevents accidental data loss
- Small inconvenience, big safety
Choose Tools Wisely
- Pick editor you’re comfortable with
- Configure terminal you know
- Integrations save time
Update Regularly
- Keep GitHub Desktop up to date
- New features and fixes
- Better performance
Backup Configuration
- Export or document your settings
- Makes reinstall easier
- Share setup across machines

Troubleshooting

Preferences Not Saving

If preferences don’t persist:

Check file permissions on config directory
Ensure disk has space
Try running as administrator (Windows)
Check for antivirus interference

Editor Not Detected

If your editor doesn’t appear:

Reinstall the editor
Check installation path
Try restarting GitHub Desktop
Select “Other” and browse to executable

Theme Not Applying

If theme changes don’t work:

Restart GitHub Desktop
Check OS theme settings (for System theme)
Try a different theme
Check for app updates

Git Identity Not Working

If commits show wrong author:

Check global Git config: git config --global user.name
Verify email: git config --global user.email
Check repository-specific config: git config user.name
Ensure no typos in email address

Get Started

Core Features

Advanced Workflows

Integrations

Configuration

Help & Support

​Overview

Appearance

Git Configuration

Integrations

Advanced Options

​Accessing Preferences

​Accounts

​GitHub and GitHub Enterprise

​Appearance

​Theme Selection

​Application Theme Implementation

​Git Configuration

​User Identity

​Default Branch Name

​Commit Behavior

​Integrations

​External Editor

​Terminal/Shell

​Shell Configuration

​Advanced Settings

​Proxy Configuration

​Repository Storage Location

​Confirmation Dialogs

​Background Operations

​Diff Display

​Experimental Features

​Preference Storage

​Configuration Files

​App State

​Resetting Preferences

​Keyboard Shortcuts

​General

​View Shortcuts

​Best Practices

​Troubleshooting

​Related Topics

Build docs developers (and LLMs) love

Overview

Accessing Preferences

Accounts

GitHub and GitHub Enterprise

Appearance

Theme Selection

Application Theme Implementation

Git Configuration

User Identity

Default Branch Name

Commit Behavior

Integrations

External Editor

Terminal/Shell

Shell Configuration

Advanced Settings

Proxy Configuration

Repository Storage Location

Confirmation Dialogs

Background Operations

Diff Display

Experimental Features

Preference Storage

Configuration Files

App State

Resetting Preferences

Keyboard Shortcuts

General

View Shortcuts

Best Practices

Troubleshooting

Related Topics