GitFlow Documentation

GitFlow is a free, professional-grade Git GUI for macOS, designed to make Git safe, understandable, and powerful for developers of all skill levels.

Installation

Download the latest release from GitHub and drag GitFlow to your Applications folder.

Download Options

• DMG Installer: Download the .dmg file from the releases page
• Homebrew: brew tap nicolas-arsenault/tap && brew install --cask gitflow-gui

First Launch

On first launch, macOS may show a security warning since the app is not notarized. To open it:

1. Right-click the app in Finder
2. Select "Open" from the context menu
3. Click "Open" in the dialog

Quick Start

Get up and running with GitFlow in under a minute.

Open a Repository

Use Cmd + O or drag a folder onto the GitFlow icon to open a repository.

Clone a Repository

1. Use Cmd + Shift + O to open the clone dialog
2. Enter the repository URL (HTTPS or SSH)
3. Choose a destination folder
4. Click "Clone"

System Requirements

Repository Management

GitFlow provides comprehensive repository management capabilities.

Repository Overview

When you open a repository, the overview screen displays:

• Current branch or detached HEAD state
• Working tree status (clean or dirty)
• Ahead/behind counts relative to upstream
• Active remotes and their URLs
• Last fetch timestamp

Recent Repositories

Access recently opened repositories from the welcome screen or via Cmd + Shift + R.

Staging & Commits

GitFlow offers granular control over what goes into each commit.

File States

Files in your working directory can be in these states:

• Untracked: New files not yet added to Git
• Modified: Tracked files with changes
• Deleted: Tracked files that have been removed
• Renamed: Files that have been moved or renamed
• Copied: Duplicated files

Partial Staging

Stage exactly what you want to commit:

• Stage file: Click the + icon next to any file
• Stage hunk: Click "Stage Hunk" in the diff view
• Stage lines: Select specific lines and choose "Stage Selected Lines"

Creating Commits

1. Stage your changes
2. Write a commit message (follow the Conventional Commits format)
3. Press Cmd + Enter or click "Commit"

Amending Commits

To modify the most recent commit:

1. Check "Amend previous commit" below the commit message
2. The previous commit message will be loaded
3. Make changes and commit

Branch Management

Comprehensive branch operations with safety guardrails.

Branch Operations

• Create branch: Cmd + B
• Switch branch: Double-click in the branch list or use Cmd + Shift + B
• Rename branch: Right-click → Rename
• Delete branch: Right-click → Delete (with safety confirmation)

Branch Safety

GitFlow prevents accidental data loss:

• Confirmation required before deleting unmerged branches
• Warnings displayed for branches with unpushed commits
• Current branch is protected from deletion

Comparing Branches

Select two branches and choose "Compare" to see:

• Commits unique to each branch
• Full diff of all changes between branches
• File-by-file comparison

Diff Visualization

GitFlow's diff engine is a core feature, designed for professional code review workflows.

View Modes

Word-Level Highlighting

Changes within lines are highlighted at the token level:

• Identifiers and keywords
• String literals
• Numbers and operators
• Whitespace changes

Diff Contexts

View diffs for various comparisons:

• Working tree vs staged (index)
• Staged vs last commit (HEAD)
• Commit vs its parent
• Any two commits
• Branch vs branch
• Local vs remote branch

Syntax Highlighting

Automatic language detection with support for 100+ languages. Colors are designed to work with diff highlighting, not against it.

Merge & Rebase

Merge Options

• Fast-forward: When possible, moves the branch pointer without a merge commit
• No fast-forward: Always creates a merge commit
• Squash: Combines all commits into one

Interactive Rebase

Visual interface for rewriting history:

• Drag to reorder commits
• Squash multiple commits together
• Edit commit messages
• Drop unwanted commits

Conflict Resolution

When conflicts occur, GitFlow displays:

• Clear OURS / THEIRS / BASE sections
• One-click "Accept Ours" or "Accept Theirs"
• Manual edit mode for complex resolutions

Remote Operations

Fetch

Download changes from remote without merging. Use Cmd + Shift + F or enable auto-fetch in preferences.

Pull

Fetch and integrate changes:

• Pull (merge): Creates a merge commit if needed
• Pull (rebase): Replays your commits on top of upstream

Push

Upload your commits to the remote. GitFlow will warn you about:

• Pushing to protected branches
• Non-fast-forward pushes (requires force push)

Stash Management

Temporarily save changes without committing.

Stash Operations

• Create stash: Cmd + Shift + S
• Apply stash: Restores changes, keeps stash
• Pop stash: Restores changes, removes stash
• Drop stash: Deletes stash permanently

Submodules

GitFlow detects and displays submodule status.

Submodule Features

• View submodule status in the file list
• Initialize and update submodules
• Open submodule as separate repository

Configuration

Access preferences via Cmd + ,

Available Settings

• Git binary path: Use a custom Git installation
• Default pull strategy: Merge or rebase
• Auto-fetch interval: Disable or set frequency
• Theme: Light, dark, or system
• External tools: Configure diff and merge tools

Keyboard Shortcuts

Troubleshooting

GitFlow can't find Git

Ensure Git is installed and accessible:

which git
git --version

If using a custom Git installation, set the path in Preferences → Git → Git Binary Path.

Authentication failures

• HTTPS: Ensure your credentials are stored in Keychain or use a personal access token
• SSH: Verify your SSH agent is running: ssh-add -l

Repository appears corrupted

Try running Git's built-in repair:

git fsck --full
git gc --prune=now

Report Issues

Found a bug? Please report it on our GitHub Issues page with:

• macOS version
• GitFlow version
• Steps to reproduce
• Relevant logs (Help → Show Logs)