Skip to content

Getting Started

Jump to bottom
Prince Lad edited this page Jan 27, 2026 · 3 revisions

Getting Started

Requirements

  • Rust 1.70+ (install from rustup.rs)
  • Git 2.0+ (for Git operations)
  • Terminal with 256-color support (most modern terminals work)

Installation

From Source

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

The binary will be available at ./target/release/forge.

Optional: Add to PATH

# Copy to a directory in your PATH
cp target/release/forge ~/.local/bin/
# or
sudo cp target/release/forge /usr/local/bin/

First Run

  1. Navigate to a Git repository:

    cd /path/to/your/git/repo

  2. Start Forge:

    forge

  3. Explore the UI:

    • Use Tab to navigate between panels
    • Use Arrow keys to move through lists
    • Press ? to see the help overlay with all keybindings
    • Press Esc to go back or cancel

Basic Workflow

Viewing Changes

  1. Navigate to the Changes screen (Tab through menus)
  2. Use arrow keys to select a file
  3. Press Space to stage/unstage files
  4. Type a commit message in the bottom input
  5. Press Enter to commit

Managing Branches

  1. Go to Branch Manager
  2. Use arrow keys to select a branch
  3. Press Enter to switch
  4. Press n to create a new branch
  5. Press d to delete a branch

Tracking Tasks

  1. Navigate to Project Board
  2. View modules organized by status (Pending → Current → Completed)
  3. Press n to create a new module
  4. Press e to edit module details
  5. Press d to delete a module

Viewing History

  1. Open Commit History
  2. Use arrow keys to browse commits
  3. Right pane shows full commit details
  4. View files changed and messages

Remote Operations

  • Press f in Dashboard or Changes to fetch from origin with progress
  • Press p in Changes to push the current branch to origin
  • Press Ctrl+L in Changes to pull and merge from origin (cancellable)

Configuration

Settings are accessible from the main menu:

  • Theme: Default or High Contrast
  • Notifications: On/Off (future feature)
  • Autosync: On/Off (future feature)

Configuration persists in:

  • .forge — Module and developer data
  • .git/forge — Merge and progress tracking

Troubleshooting

"No Git repository found"

  • Ensure you're in a directory with a .git folder
  • Run git init to initialize a new repo

"Terminal too small"

  • Resize your terminal to at least 80×24 characters
  • Forge will display a size warning if needed

"Keybindings not responding"

  • Press ? to see available keybindings for the current screen
  • Some terminal emulators may not support certain key combinations
  • Try a different terminal if issues persist

Next Steps

Clone this wiki locally