Project 4: A lazygit-style Git Client with Go & Bubbletea

A multi-pane TUI for managing a Git repository. It will have panels for unstaged files, staged files, and recent commits. You’ll be able to stage files and write commit messages.

Quick Reference

Attribute Value
Primary Language Go
Alternative Languages Rust (with Ratatui)
Difficulty Level 3: Advanced
Time Estimate 2-3 weeks
Knowledge Area Modern TUI Frameworks / Git
Tooling Go, Bubbletea & Lipgloss libraries, Git
Prerequisites Basic Go programming, familiarity with Git commands.

What You Will Build

A multi-pane TUI for managing a Git repository. It will have panels for unstaged files, staged files, and recent commits. You’ll be able to stage files and write commit messages.

Why It Matters

This project builds core skills that appear repeatedly in real-world systems and tooling.

Core Challenges

  • Structuring the app with Model-View-Update → maps to learning the Elm architecture
  • Creating a multi-pane layout → maps to using lipgloss for flexbox-like styling
  • Executing shell commands (git) and parsing their output → maps to handling asynchronous operations and commands (Cmds)
  • Managing focus between different panels → maps to complex state management in your Model

Key Concepts

  • The Elm Architecture: Bubbletea documentation.
  • Styling with Lipgloss: Lipgloss documentation for borders, padding, colors.
  • Bubbletea Commands (Cmds): How to perform I/O without blocking the UI loop.
  • Component Composition: Building smaller models (like a list view) and combining them in a parent model.

Real-World Outcome

(Terminal Output)
┌───────────GIT STATUS─────────────┐┌───────────RECENT COMMITS───────────────┐
│ Status in /path/to/repo          ││ > feat: Add new TUI layout (HEAD)      │
│ ▽ Staged Changes (1)             ││   fix: Correct off-by-one error        │
│   M internal/ui/view.go          ││   refactor: Simplify state management  │
│ ▽ Unstaged Changes (2)           ││   docs: Update README for new feature  │
│ >?? .gitignore                   ││                                        │
│  AM main.go                      ││                                        │
└──────────────────────────────────┘└────────────────────────────────────────┘
┌───────────────────────────────────────────────────────────────────────────┐
│ Diff for main.go                                                          │
│@@ -10,5 +10,6 @@                                                           │
│ import (                                                                  │
│-   "fmt"                                                                   │
│+   "fmt"                                                                   │
│+   "os/exec"                                                               │
│ )                                                                         │
└───────────────────────────────────────────────────────────────────────────┘
 [s]tage [c]ommit [q]uit

Implementation Guide

  1. Reproduce the simplest happy-path scenario.
  2. Build the smallest working version of the core feature.
  3. Add input validation and error handling.
  4. Add instrumentation/logging to confirm behavior.
  5. Refactor into clean modules with tests.

Milestones

  • Milestone 1: Minimal working program that runs end-to-end.
  • Milestone 2: Correct outputs for typical inputs.
  • Milestone 3: Robust handling of edge cases.
  • Milestone 4: Clean structure and documented usage.

Validation Checklist

  • Output matches the real-world outcome example
  • Handles invalid inputs safely
  • Provides clear errors and exit codes
  • Repeatable results across runs

References

  • Main guide: LEARN_TUI_PROGRAMMING_PROJECTS.md
  • “The Go Programming Language” by Donovan & Kernighan