GitFlow Documentation

GitFlow is a Git GUI for macOS with the most advanced diff visualization engine. Powered by SwiftSyntax for structural code analysis, GitFlow helps you understand code changes at a deeper level than line-by-line diffs.

Installation

Install GitFlow with a single command. The installer automatically downloads the latest release and configures everything for you.

Quick Install

Run this command in Terminal:

curl -fsSL https://raw.githubusercontent.com/Nicolas-Arsenault/GitFlow/main/scripts/install.sh | bash

The installer will:

• Detect the latest release from GitHub
• Download the DMG file
• Install GitFlow to /Applications
• Remove quarantine attributes (no security warnings)
• Clean up temporary files

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 the core of the application, designed for professional code review workflows with structural code analysis.

Structural Diff View

Powered by SwiftSyntax AST parsing, GitFlow can show you what code structures changed:

• Added functions: New functions, methods, and closures
• Modified functions: Existing functions that changed
• Removed functions: Deleted code structures
• Class/struct changes: Type modifications at a glance

Semantic Equivalence Detection

GitFlow can detect when changes don't affect behavior:

• Reformatting and whitespace changes
• Variable renames (when locally scoped)
• Import reordering
• Comment-only changes

Change Impact Analysis

See how your changes affect the rest of the codebase:

• Functions that call the modified code
• Types that depend on changed structures
• Potential breaking changes

View Modes

Word-Level Highlighting

Changes within lines are highlighted at the token level:

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

Syntax Highlighting

Automatic language detection with support for 200+ 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

GitHub Integration

GitFlow provides deep integration with GitHub for a complete workflow without leaving the app.

Authentication

GitFlow uses OAuth for secure GitHub authentication:

1. Go to Preferences → GitHub
2. Click "Sign in with GitHub"
3. Authorize GitFlow in your browser
4. You're connected!

Repository Browsing

Once authenticated, you can:

• Browse your repositories and organizations
• Clone repositories directly from the app
• See repository metadata and descriptions

Pull Requests

Full pull request workflow support:

• Create PRs: Create pull requests from branches with title and description
• Review PRs: View diffs, add comments, approve or request changes
• Merge PRs: Merge, squash, or rebase directly from GitFlow
• Close PRs: Close without merging if needed

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)