Home

Forge Wiki

Welcome to the Forge documentation hub. Forge is a developer-first, terminal-based Git-aware project management system that integrates version control with lightweight task tracking in a single TUI workflow.

Quick Links

• Getting Started — Installation, build, and first run
• Features — Complete feature overview and current state
• Architecture — System design, modules, and data flow
• Keyboard Shortcuts — Complete keybinding reference
• Development — Contributing guide and code structure
• API Reference — Core types and functions
• Workflows — User workflows and interaction patterns
• Performance — Benchmarks and optimization guidelines
• Roadmap — Future features and planned work
• FAQ — Common questions and troubleshooting

What is Forge?

Forge answers a core question:

Can a developer manage project context, tasks, and code changes from a single terminal interface without breaking their coding flow?

Key Capabilities

• 🔀 Git Integration — Real-time file status and diff preview
• 📋 Project Board — Kanban-style task management (Pending → Current → Completed)
• 🔗 Branch Management — Create, switch, and delete branches
• 📝 Commit History — Browse and inspect commit details
• 👥 Team Management — Track modules and developers
• 🔀 Merge Visualization — Side-by-side conflict resolution
• ⚙️ Customizable — Theme switching and settings

Getting Started

1. Clone and build:

   git clone https://github.com/Princelad/forge.git
   cd forge
   cargo build --release

2. Run in a Git repository:

   ./target/release/forge

3. Navigate with keyboard — Press ? for help overlay

Project State

✅ Implemented

• Terminal UI with multi-pane layouts
• Git repository auto-discovery and status tracking
• Real-time diff preview and file staging
• Branch operations (create, switch, delete)
• Commit history browser (last 50 commits)
• Module and developer CRUD management
• Data persistence (.forge and .git/forge)
• Settings and theme customization
• Merge conflict visualization

🔄 Not Yet Implemented

• Remote operations (push, pull, fetch)
• Automated task inference from Git history
• AI/ML commit message generation
• Multi-repository support

Core Screens

Screen	Purpose
Dashboard	Project overview with metadata and statistics
Project Board	Kanban board for task management
Changes	File staging, diffing, and committing
Commit History	Browse commits with full details
Branch Manager	Create, switch, and delete branches
Merge Visualizer	Resolve conflicts with side-by-side diffs
Module Manager	Manage modules and developers
Settings	Theme and behavior configuration

Tech Stack

• Language: Rust
• UI Framework: ratatui
• Git Integration: git2-rs
• Error Handling: color-eyre

License

GPL-3.0-only

---

Additional Resources:

• CHANGELOG.md — Version history and release notes
• CONTRIBUTING.md — Quick contributing guide

---

Need help? Check the FAQ or open an issue on GitHub.