# jesseduffield/lazygit architecture

> Architecture diagram of the GitHub repository jesseduffield/lazygit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jesseduffield/lazygit
- Repository: https://github.com/jesseduffield/lazygit

## Overview

Lazygit is a terminal UI for operating on Git repositories. The user starts the app, navigates repository views, and invokes Git actions through context-specific controllers; those actions use Git command services, while results are presented in the UI. The tree and excerpts identify core areas for commits, files, branches, remotes, stashes, worktrees, conflict handling, custom commands, and background tasks. Some subsystem links are based on the SOURCE INDEX or README; unsampled implementations are represented at their supported directory paths, not treated as inspected.

Main entry points: [`pkg/gui/controllers.go`](https://github.com/jesseduffield/lazygit/blob/master/pkg/gui/controllers.go) (UI controllers), [`pkg/commands/git_commands`](https://github.com/jesseduffield/lazygit/tree/master/pkg/commands/git_commands) (Git command services), [`pkg/app/app.go`](https://github.com/jesseduffield/lazygit/blob/master/pkg/app/app.go) (App bootstrap), [`pkg/gui/gui.go`](https://github.com/jesseduffield/lazygit/blob/master/pkg/gui/gui.go) (Terminal UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_startup["Startup and configuration"]
  node_app["App bootstrap<br/>[app.go]"]
  node_config["User configuration"]
end

subgraph group_interaction["UI and interaction"]
  node_gui["Terminal UI<br/>[gui.go]"]
  node_controllers["UI controllers<br/>[controllers.go]"]
  node_branch_actions["Branch actions"]
  node_file_actions["File and diff actions"]
  node_commit_actions["Commit history actions"]
  node_main_view["Diff navigation"]
  node_contexts["View contexts"]
  node_presentation["Repository presentation"]
  node_custom_commands["Custom commands<br/>[handler_creator.go]"]
end

subgraph group_git["Git operations"]
  node_git_commands["Git command services"]
  node_command_runner["Process execution"]
  node_models["Git data models"]
  node_hosting["Hosting integration<br/>[hosting_service.go]"]
end

subgraph group_support["Runtime support"]
  node_tasks["Async tasks<br/>[tasks.go]"]
  node_gui_tasks["UI task adapter<br/>[tasks_adapter.go]"]
  node_updates["Update checking<br/>[updates.go]"]
end

node_user(("Terminal user"))
node_git_repo[("Git repository")]
node_hosting_service{{"Hosting provider"}}

node_user -->|"starts"| node_app
node_app -->|"runs"| node_gui
node_app -->|"loads"| node_config
node_app -->|"initializes"| node_git_commands
node_app -->|"creates updater"| node_updates
node_user -.->|"interacts"| node_gui
node_gui -->|"attaches"| node_controllers
node_controllers -->|"registers"| node_branch_actions
node_controllers -->|"registers"| node_file_actions
node_controllers -->|"registers"| node_commit_actions
node_controllers -->|"registers"| node_main_view
node_controllers -->|"configures"| node_custom_commands
node_branch_actions -->|"invokes"| node_git_commands
node_file_actions -->|"invokes"| node_git_commands
node_commit_actions -->|"invokes"| node_git_commands
node_file_actions -->|"uses"| node_models
node_branch_actions -->|"uses"| node_models
node_commit_actions -->|"operates on"| node_contexts
node_main_view -->|"navigates"| node_contexts
node_git_commands -.->|"executes via"| node_command_runner
node_command_runner -.->|"runs Git against"| node_git_repo
node_git_commands -->|"delegates hosting"| node_hosting
node_hosting -.->|"connects"| node_hosting_service
node_gui_tasks -->|"adapts"| node_tasks
node_gui -.->|"renders"| node_presentation

click node_app "https://github.com/jesseduffield/lazygit/blob/master/pkg/app/app.go"
click node_config "https://github.com/jesseduffield/lazygit/tree/master/pkg/config"
click node_gui "https://github.com/jesseduffield/lazygit/blob/master/pkg/gui/gui.go"
click node_controllers "https://github.com/jesseduffield/lazygit/blob/master/pkg/gui/controllers.go"
click node_branch_actions "https://github.com/jesseduffield/lazygit/blob/master/pkg/gui/controllers/branches_controller.go"
click node_file_actions "https://github.com/jesseduffield/lazygit/blob/master/pkg/gui/controllers/files_controller.go"
click node_commit_actions "https://github.com/jesseduffield/lazygit/blob/master/pkg/gui/controllers/local_commits_controller.go"
click node_main_view "https://github.com/jesseduffield/lazygit/blob/master/pkg/gui/controllers/main_view_controller.go"
click node_contexts "https://github.com/jesseduffield/lazygit/tree/master/pkg/gui/context"
click node_presentation "https://github.com/jesseduffield/lazygit/tree/master/pkg/gui/presentation"
click node_git_commands "https://github.com/jesseduffield/lazygit/tree/master/pkg/commands/git_commands"
click node_command_runner "https://github.com/jesseduffield/lazygit/tree/master/pkg/commands/oscommands"
click node_models "https://github.com/jesseduffield/lazygit/tree/master/pkg/commands/models"
click node_custom_commands "https://github.com/jesseduffield/lazygit/blob/master/pkg/gui/services/custom_commands/handler_creator.go"
click node_tasks "https://github.com/jesseduffield/lazygit/blob/master/pkg/tasks/tasks.go"
click node_gui_tasks "https://github.com/jesseduffield/lazygit/blob/master/pkg/gui/tasks_adapter.go"
click node_hosting "https://github.com/jesseduffield/lazygit/blob/master/pkg/commands/hosting_service/hosting_service.go"
click node_updates "https://github.com/jesseduffield/lazygit/blob/master/pkg/updates/updates.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_config,node_user toneBlue
class node_gui,node_controllers,node_branch_actions,node_file_actions,node_commit_actions,node_main_view,node_contexts,node_presentation,node_custom_commands,node_git_repo toneAmber
class node_git_commands,node_command_runner,node_models,node_hosting toneMint
class node_tasks,node_gui_tasks,node_updates toneRose
class node_hosting_service toneIndigo
```

## Components

### Startup and configuration

- [App bootstrap](https://github.com/jesseduffield/lazygit/blob/master/pkg/app/app.go): `pkg/app/app.go`
- [User configuration](https://github.com/jesseduffield/lazygit/tree/master/pkg/config): `pkg/config`

### UI and interaction

- [Terminal UI](https://github.com/jesseduffield/lazygit/blob/master/pkg/gui/gui.go): `pkg/gui/gui.go`
- [UI controllers](https://github.com/jesseduffield/lazygit/blob/master/pkg/gui/controllers.go): `pkg/gui/controllers.go`
- [Branch actions](https://github.com/jesseduffield/lazygit/blob/master/pkg/gui/controllers/branches_controller.go): `pkg/gui/controllers/branches_controller.go`
- [File and diff actions](https://github.com/jesseduffield/lazygit/blob/master/pkg/gui/controllers/files_controller.go): `pkg/gui/controllers/files_controller.go`
- [Commit history actions](https://github.com/jesseduffield/lazygit/blob/master/pkg/gui/controllers/local_commits_controller.go): `pkg/gui/controllers/local_commits_controller.go`
- [Diff navigation](https://github.com/jesseduffield/lazygit/blob/master/pkg/gui/controllers/main_view_controller.go): `pkg/gui/controllers/main_view_controller.go`
- [View contexts](https://github.com/jesseduffield/lazygit/tree/master/pkg/gui/context): `pkg/gui/context`
- [Repository presentation](https://github.com/jesseduffield/lazygit/tree/master/pkg/gui/presentation): `pkg/gui/presentation`
- [Custom commands](https://github.com/jesseduffield/lazygit/blob/master/pkg/gui/services/custom_commands/handler_creator.go): `pkg/gui/services/custom_commands/handler_creator.go`

### Git operations

- [Git command services](https://github.com/jesseduffield/lazygit/tree/master/pkg/commands/git_commands): `pkg/commands/git_commands`
- [Process execution](https://github.com/jesseduffield/lazygit/tree/master/pkg/commands/oscommands): `pkg/commands/oscommands`
- [Git data models](https://github.com/jesseduffield/lazygit/tree/master/pkg/commands/models): `pkg/commands/models`
- [Hosting integration](https://github.com/jesseduffield/lazygit/blob/master/pkg/commands/hosting_service/hosting_service.go): `pkg/commands/hosting_service/hosting_service.go`

### Runtime support

- [Async tasks](https://github.com/jesseduffield/lazygit/blob/master/pkg/tasks/tasks.go): `pkg/tasks/tasks.go`
- [UI task adapter](https://github.com/jesseduffield/lazygit/blob/master/pkg/gui/tasks_adapter.go): `pkg/gui/tasks_adapter.go`
- [Update checking](https://github.com/jesseduffield/lazygit/blob/master/pkg/updates/updates.go): `pkg/updates/updates.go`

### Other components

- **Terminal user**
- **Git repository**
- **Hosting provider**

## Connections

- Terminal user → App bootstrap: starts (evidence: `README.md`)
- App bootstrap → Terminal UI: runs (evidence: `pkg/app/app.go`)
- App bootstrap → User configuration: loads (evidence: `pkg/app/app.go`)
- App bootstrap → Git command services: initializes (evidence: `pkg/app/app.go`)
- App bootstrap → Update checking: creates updater (evidence: `pkg/app/app.go`)
- Terminal user → Terminal UI: interacts
- Terminal UI → UI controllers: attaches (evidence: `pkg/gui/controllers.go`)
- UI controllers → Branch actions: registers (evidence: `pkg/gui/controllers.go`)
- UI controllers → File and diff actions: registers (evidence: `pkg/gui/controllers.go`)
- UI controllers → Commit history actions: registers (evidence: `pkg/gui/controllers.go`)
- UI controllers → Diff navigation: registers (evidence: `pkg/gui/controllers.go`)
- UI controllers → Custom commands: configures (evidence: `pkg/gui/controllers.go`)
- Branch actions → Git command services: invokes (evidence: `pkg/gui/controllers/branches_controller.go`)
- File and diff actions → Git command services: invokes (evidence: `pkg/gui/controllers/files_controller.go`)
- Commit history actions → Git command services: invokes (evidence: `pkg/gui/controllers/local_commits_controller.go`)
- File and diff actions → Git data models: uses (evidence: `pkg/gui/controllers/files_controller.go`)
- Branch actions → Git data models: uses (evidence: `pkg/gui/controllers/branches_controller.go`)
- Commit history actions → View contexts: operates on (evidence: `pkg/gui/controllers/local_commits_controller.go`)
- Diff navigation → View contexts: navigates (evidence: `pkg/gui/controllers/main_view_controller.go`)
- Git command services → Process execution: executes via
- Process execution → Git repository: runs Git against
- Git command services → Hosting integration: delegates hosting (evidence: `pkg/commands/git_commands/hosting_service.go`)
- Hosting integration → Hosting provider: connects
- UI task adapter → Async tasks: adapts (evidence: `pkg/gui/tasks_adapter.go`)
- Terminal UI → Repository presentation: renders
