Committing Changes - GitHub Desktop

Overview

Committing changes is at the heart of Git workflows. GitHub Desktop provides an intuitive interface for reviewing changes, staging files, and creating meaningful commits.

Visual Diff

See exactly what changed with syntax-highlighted diffs

Selective Staging

Stage individual files or specific line changes

Commit Messages

Write descriptive commit messages with title and description

Git Hooks

Support for pre-commit, commit-msg, and post-commit hooks

Understanding the Changes View

Changes List

The left sidebar shows all modified files in your working directory:

Checkboxes: Select which files to include in the commit
File Icons: Visual indicators for file status
- Green +: New file (untracked)
- Yellow M: Modified file
- Red -: Deleted file
- Blue R: Renamed file
- Purple C: Copied file
- Gray ?: Untracked file

Diff Viewer

The main panel displays the diff for the selected file:

Line-by-line changes: See exactly what was added, removed, or modified
Syntax highlighting: Code appears with proper syntax coloring
Split/unified view: Toggle between side-by-side and unified diff views
Expand context: Click to show more surrounding lines

Creating a Commit

Review Changes

Check the Changes list to see all modified files in your repository

Stage Files

Select which files to include:

Check individual files to stage them
Click Select All to stage all changes
Uncheck files you want to exclude

Write Commit Message

In the commit message box at the bottom:

Summary: Brief description (required, ~50 characters)
Description: Detailed explanation (optional, supports markdown)

Commit to Branch

Click Commit to [branch-name] to create the commit

GitHub Desktop clears the staging area before each commit, ensuring your commits reflect the exact state shown in the diff viewer.

Commit Implementation

GitHub Desktop’s commit implementation includes several advanced features:

// From app/src/lib/git/commit.ts
export async function createCommit(
  repository: Repository,
  message: string,
  files: ReadonlyArray<WorkingDirectoryFileChange>,
  options?: {
    amend?: boolean
    noVerify?: boolean
  }
): Promise<string> {
  // Clear the staging area
  await unstageAll(repository)
  
  // Stage selected files
  await stageFiles(repository, files)
  
  const args = ['-F', '-']  // Read message from stdin
  
  if (options?.amend) {
    args.push('--amend')
  }
  
  if (options?.noVerify) {
    args.push('--no-verify')
  }
  
  const result = await git(
    ['commit', ...args],
    repository.path,
    'createCommit',
    {
      stdin: message,
      interceptHooks: [
        'pre-commit',
        'prepare-commit-msg',
        'commit-msg',
        'post-commit',
        'pre-auto-gc',
      ]
    }
  )
  
  return parseCommitSHA(result)
}

Partial Commits (Staging Specific Lines)

Stage specific line changes within a file:

Select File

Click on a modified file in the Changes list

Choose Lines

In the diff viewer, click the line numbers or drag to select lines

Stage Selection

Right-click the selection and choose Stage Selected Lines

Commit

The staged lines will be included in your next commit

Use partial commits to create more focused, logical commits even when you’ve made multiple unrelated changes to a single file.

Writing Good Commit Messages

Message Structure

A well-formatted commit message consists of:

Summary Line (required):
- Brief description of changes
- ~50 characters (hard limit: 72)
- Imperative mood: “Add feature” not “Added feature”
- No period at the end
Description (optional):
- Detailed explanation of what and why
- Supports markdown formatting
- Wrap at 72 characters per line
- Include context, motivation, and implementation notes

Examples

Add user authentication with OAuth 2.0

Implement OAuth 2.0 authentication flow using GitHub as the
provider. This allows users to sign in without creating a
separate account.

Changes:
- Add OAuth callback handler
- Implement token refresh logic
- Store encrypted tokens in keychain

Fixes #123

Commit Message Tips

Be Specific

“Fix login bug” → “Fix session timeout in OAuth flow”

Explain Why

Include the reason for the change, not just what changed

Reference Issues

Link to issues with “Fixes #123” or “Relates to #456”

Use Imperative

“Add feature” not “Added feature” or “Adds feature”

Amending Commits

Modify your most recent commit:

Make Changes

Edit files you want to include in the amended commit

Stage Files

Select the files to add to the commit

Amend Commit

Check Amend last commit at the bottom of the commit message area

Update Message (Optional)

Modify the commit message if needed

Commit

Click Amend last commit to update the commit

Never amend commits that have been pushed to a shared branch. Amending rewrites Git history and can cause issues for collaborators.

Git Hooks Support

GitHub Desktop fully supports Git hooks that run during the commit process:

Supported Hooks

pre-commit

Runs before creating the commit. Common uses:

Linting code
Running tests
Checking code formatting

If the hook fails, the commit is aborted.

prepare-commit-msg

Runs after the default message is created but before the editor is shown. Used to:

Auto-generate commit messages
Add ticket numbers
Include template text

commit-msg

Validates the commit message. Used to:

Enforce commit message format
Require issue references
Check message length

If the hook fails, the commit is aborted.

post-commit

Runs after the commit is created. Used for:

Notifications
Triggering CI/CD
Logging

Cannot affect the commit outcome.

Hook Output

When a hook runs, GitHub Desktop:

Shows progress indicator
Displays hook output in real-time
Allows aborting long-running hooks
Shows error messages if hooks fail

Co-authoring Commits

Add co-authors to commits for pair programming:

Write Commit Message

Enter your commit summary and description as usual

Add Co-authors

Click the Add Co-authors button or icon

Select Co-authors

Choose from recent collaborators or enter manually:

Co-authored-by: Name <[email protected]>

Commit

Create the commit with co-author attribution

Co-authored commits appear on both authors’ GitHub profiles.

Merge Commits

When completing a merge with conflicts, GitHub Desktop creates a merge commit:

// From app/src/lib/git/commit.ts
export async function createMergeCommit(
  repository: Repository,
  files: ReadonlyArray<WorkingDirectoryFileChange>,
  manualResolutions: ReadonlyMap<string, ManualConflictResolution> = new Map()
): Promise<string> {
  // Apply manual conflict resolutions
  for (const [path, resolution] of manualResolutions) {
    await stageManualConflictResolution(repository, file, resolution)
  }
  
  await stageFiles(repository, otherFiles)
  
  const result = await git(
    [
      'commit',
      '--no-edit',        // Use existing merge message
      '--cleanup=strip',  // Remove comment lines
    ],
    repository.path,
    'createMergeCommit'
  )
  
  return parseCommitSHA(result)
}

Merge commits automatically use the message generated by Git, which includes information about the merged branches.

Discarding Changes

Revert uncommitted changes:

Discard All Changes

Right-Click Files

Right-click in the Changes list

Discard All Changes

Select Discard all changes

Confirm

Confirm the action in the dialog

Discard Specific Files

Right-click a file > Discard changes
Or select multiple files and right-click > Discard changes

Discarding changes is permanent and cannot be undone. The changes are not saved to stash.

Viewing Commit History

Switch to the History tab to see previous commits:

Chronological list of commits
Commit message, author, and timestamp
Changed files for each commit
Visual representation of branch structure

Commit Warnings

GitHub Desktop displays warnings for:

Large commits: More than 100 files changed
Large files: Files over 100MB
Protected files: System files or sensitive data
Unmerged files: Files with unresolved conflicts

Best Practices

Commit early and often: Small, focused commits are easier to review, understand, and revert if needed.

One Logical Change per Commit: Each commit should represent a single, complete change
Test Before Committing: Ensure your code works before creating a commit
Review Your Diff: Always check what you’re committing in the diff viewer
Write Meaningful Messages: Future you (and your teammates) will thank you
Use Descriptive Summaries: Make it easy to understand commits at a glance
Commit Related Changes Together: Don’t mix unrelated changes in a single commit

Keyboard Shortcuts

Action	Windows/Linux	macOS
Commit	`Ctrl+Enter`	`Cmd+Enter`
Select all files	`Ctrl+A`	`Cmd+A`
Deselect all	`Ctrl+Shift+A`	`Cmd+Shift+A`
Show in diff	`Enter`	`Enter`
Toggle file selection	`Space`	`Space`

Troubleshooting

Commit Button Disabled

The commit button is disabled when:

No files are selected for staging
No commit message is entered
A hook is currently running

Ensure you’ve selected files and written a commit message.

Hook Failures

If a pre-commit or commit-msg hook fails:

Read the error message in the hook output dialog
Fix the issues identified by the hook
Try committing again
Use --no-verify flag (Repository menu) to skip hooks if necessary

Cannot Amend Commit

You cannot amend if:

There are no commits in the repository
The commit has been pushed to a protected branch
You’re in a rebase, merge, or cherry-pick state

Get Started

Core Features

Advanced Workflows

Integrations

Configuration

Help & Support

​Overview

Visual Diff

Selective Staging

Commit Messages

Git Hooks

​Understanding the Changes View

​Changes List

​Diff Viewer

​Creating a Commit

​Commit Implementation

​Partial Commits (Staging Specific Lines)

​Writing Good Commit Messages

​Message Structure

​Examples

​Commit Message Tips

Be Specific

Explain Why

Reference Issues

Use Imperative

​Amending Commits

​Git Hooks Support

​Supported Hooks

​Hook Output

​Co-authoring Commits

​Merge Commits

​Discarding Changes

​Discard All Changes

​Discard Specific Files

​Viewing Commit History

​Commit Warnings

​Best Practices

​Keyboard Shortcuts

​Troubleshooting

​Related Topics

Build docs developers (and LLMs) love

Overview

Understanding the Changes View

Changes List

Diff Viewer

Creating a Commit

Commit Implementation

Partial Commits (Staging Specific Lines)

Writing Good Commit Messages

Message Structure

Examples

Commit Message Tips

Amending Commits

Git Hooks Support

Supported Hooks

Hook Output

Co-authoring Commits

Merge Commits

Discarding Changes

Discard All Changes

Discard Specific Files

Viewing Commit History

Commit Warnings

Best Practices

Keyboard Shortcuts

Troubleshooting

Related Topics