Overview

Relevant source files

• Guitar.pri
• Guitar.pro
• src/ApplicationGlobal.cpp
• src/ApplicationGlobal.h
• src/Git.cpp
• src/Git.h
• src/MainWindow.cpp
• src/MainWindow.h
• src/MainWindow.ui
• src/main.cpp

Guitar is a cross-platform graphical Git client built with Qt. It provides a comprehensive interface for managing Git repositories, visualizing commit history with branch graphs, viewing file diffs side-by-side, and performing common Git operations. The application integrates advanced features including AI-powered commit message generation, avatar loading from remote services, and direct Git object manipulation for performance optimization.

This page provides a high-level overview of Guitar's architecture and components. For detailed information about specific subsystems, see:

• Core architecture components: 2
• UI components: 3
• Advanced features like AI integration: 5
• Build system: 6

---

Application Architecture

Guitar follows a layered architecture separating presentation, business logic, data access, and external integrations. The MainWindow class serves as the central orchestrator, coordinating between UI widgets, Git operations, and external services.

Sources: src/MainWindow.h1-712 src/ApplicationGlobal.h1-126 src/Git.h1-264 src/GitRunner.h

---

Core Components

MainWindow: Central Orchestrator

The MainWindow class (src/MainWindow.cpp216-342) is the primary entry point for user interactions. It manages the application lifecycle, coordinates between UI components, and delegates Git operations to the GitRunner.

Key Responsibilities:

• Repository selection and opening (src/MainWindow.cpp196-214)
• UI component lifecycle management
• Event routing and keyboard shortcuts (src/MainWindow.cpp643-777)
• Process execution and logging (src/MainWindow.cpp488-543)

Sources: src/MainWindow.h90-703 src/MainWindow.cpp216-358

ApplicationGlobal: Singleton State Manager

ApplicationGlobal (src/ApplicationGlobal.cpp19-29) provides global access to shared resources, settings, and services throughout the application.

Managed Resources:

• ApplicationSettings appsettings - user preferences (src/ApplicationGlobal.h74)
• WebContext webcx - HTTP client context (src/ApplicationGlobal.h76)
• AvatarLoader avatar_loader - background avatar fetching (src/ApplicationGlobal.h77)
• ThemePtr theme - UI theme (dark/light) (src/ApplicationGlobal.h53)
• FileType filetype - MIME type detection (src/ApplicationGlobal.h72)

Sources: src/ApplicationGlobal.h38-125 src/ApplicationGlobal.cpp19-89

Git Command Execution Pipeline

Git operations flow through a three-layer abstraction:

1. GitRunner (src/GitRunner.h): High-level interface wrapping Git operations with repository context
2. Git (src/Git.cpp18-42): Core Git command execution with caching
3. AbstractGitSession (src/AbstractGitSession.h): Platform abstraction for process execution

Sources: src/GitRunner.h src/Git.h17-243 src/Git.cpp18-163 src/AbstractGitSession.h

Git Object Management

For performance, Guitar directly reads Git pack files instead of always invoking git cat-file:

• GitObjectCache: LRU cache for frequently accessed objects (src/Git.cpp29-37)
• GitObjectManager: Locates and loads objects from pack files (src/GitObjectManager.cpp)
• GitPack/GitPackIdxV2: Reads .pack and .idx files with delta decompression (src/GitPack.cpp src/GitPackIdxV2.cpp)

Sources: src/Git.cpp29-37 src/GitObjectManager.h src/GitPack.h src/GitPackIdxV2.h

---

User Interface Components

The UI is organized into three primary panels:

Key UI Classes

Component	Purpose	File
RepositoryTreeWidget	Repository list with groups and filtering	src/RepositoryTreeWidget.h
CommitLogTableWidget	Commit history with graph visualization	src/CommitLogTableWidget.h
FileDiffWidget	Side-by-side diff viewer with syntax highlighting	src/FileDiffWidget.h
ProgressWidget	Operation progress display	src/ProgressWidget.h
StatusLabel	Status bar information	src/StatusLabel.h

Sources: src/MainWindow.ui1-3000 src/RepositoryTreeWidget.h src/CommitLogTableWidget.h src/FileDiffWidget.h

---

Key Features

Repository Management

• Local repository bookmarks stored in guitar.ini (src/MainWindow.cpp310-312)
• Repository groups for organization (src/MainWindow.cpp964-985)
• Automatic repository detection and validation (src/Git.cpp107-139)
• SSH key association per repository (src/Git.cpp44-64)

Git Operations

Guitar supports standard Git operations through both UI and PTY processes:

• Standard operations: commit, fetch, pull, push, branch, tag, merge, rebase
• Advanced operations: stash, cherry-pick, reflog, submodule management
• GPG signing: commit signing with verification (src/gpg.h src/Git.cpp213-217)

Sources: src/Git.h122-243 src/Git.cpp147-230

Diff Visualization

The FileDiffWidget (src/FileDiffWidget.cpp) provides:

• Side-by-side diff display with synchronized scrolling
• Character-level diff highlighting using the dtl library (src/dtl/)
• Syntax highlighting via TextEditorView (src/texteditor/TextEditorView.h)
• Image diff support (src/ImageViewWidget.h)
• Minimap overview via FileDiffSliderWidget (src/FileDiffSliderWidget.h)

Sources: src/FileDiffWidget.h1-200 src/texteditor/TextEditorView.h src/dtl/dtl.hpp

AI-Powered Commit Messages

CommitMessageGenerator (src/CommitMessageGenerator.h) generates commit messages from diffs:

Sources: src/CommitMessageGenerator.h src/GenerativeAI.h src/GenerateCommitMessageThread.h

Network Integration

• WebClient (src/webclient.h): HTTP/HTTPS client with SSL support
• AvatarLoader (src/AvatarLoader.h): Background thread for fetching user avatars from GitHub
• GitHubAPI (src/GitHubAPI.h): Repository search and remote operations

Sources: src/webclient.h src/AvatarLoader.h src/GitHubAPI.h

---

Cross-Platform Support

Process Execution Abstraction

Platform-specific implementations handle:

• Standard process execution with pipes
• PTY (pseudo-terminal) for interactive operations like SSH authentication
• Windows: winpty library (Guitar.pri49-50)
• Unix: POSIX openpt, grantpt, unlockpt (Guitar.pri36)

Sources: src/AbstractProcess.h src/win32/Win32Process.h src/win32/Win32PtyProcess.h src/unix/UnixProcess.h src/unix/UnixPtyProcess.h

Build System

The project uses qmake with modular .pri files:

• Guitar.pro - Main project file (Guitar.pro1-5)
• Guitar.pri - Core configuration, dependencies, source files (Guitar.pri1-595)
• migemo.pri - Japanese incremental search support

Dependencies:

• Qt 5/6 (core, gui, widgets, svg, network) (Guitar.pri4)
• OpenSSL (static or dynamic) (Guitar.pri56-68)
• zlib (Guitar.pri77-85)
• Custom filetype library for MIME detection (Guitar.pri89-93)

Sources: Guitar.pro1-5 Guitar.pri1-100

---

Application Lifecycle

Initialization

The application initializes in this order (src/main.cpp86-269):

1. WebClient initialization (src/main.cpp89)
2. ApplicationGlobal singleton creation (src/main.cpp91-92)
3. Signal handlers (SIGTERM, SIGPIPE) (src/main.cpp93-96)
4. Command-line argument parsing (src/main.cpp104-134)
5. Configuration directory setup (src/main.cpp136-153)
6. Settings loading (src/main.cpp155)
7. QApplication creation (src/main.cpp172)
8. Theme selection (dark/light) (src/main.cpp191-207)
9. Translation loading (src/main.cpp225-237)
10. MainWindow creation and display (src/main.cpp239-243)

Sources: src/main.cpp86-269

Event Processing

The MainWindow uses a custom event queue for delayed user events (src/MainWindow.cpp432-472):

• postUserEvent() schedules events with millisecond precision
• onInterval10ms() processes queued events at 10ms intervals (src/MainWindow.cpp504-543)
• PTY process monitoring occurs in the same timer (src/MainWindow.cpp528-542)

Sources: src/MainWindow.cpp432-543 src/UserEvent.h

Settings Persistence

Settings are stored using Qt's QSettings wrapper (MySettings src/MySettings.h):

• Configuration file: {AppConfigDir}/Guitar.ini (src/main.cpp142)
• Window geometry and state (src/MainWindow.cpp786-806)
• Repository bookmarks (src/MainWindow.cpp1027-1031)
• UI preferences (language, theme, panel visibility)

Sources: src/MySettings.h src/ApplicationSettings.h src/main.cpp136-165

---

Technology Stack Summary

Layer	Technologies
UI Framework	Qt 5/6 (Widgets, SVG, Network)
Programming Language	C++17
Version Control	Direct Git command execution + pack file reading
Networking	OpenSSL (HTTPS), Qt Network
Text Editing	Custom character-based editor (AbstractCharacterBasedApplication)
Diff Algorithm	dtl library (Myers diff)
Process Management	Platform-specific (winpty on Windows, POSIX PTY on Unix)
File Type Detection	libmagic wrapper
Build System	qmake

Sources: Guitar.pri1-100 src/texteditor/AbstractCharacterBasedApplication.h src/dtl/dtl.hpp