Gitforest

A terminal UI for managing multiple Git repositories and GitHub integration.

Built with Bun, TypeScript, Ink (React for CLI), and Drizzle ORM.

Features

• Project Discovery: Scan configured directories for git repos, non-git projects, and submodules
• Git Status Dashboard: See unstaged changes, unpushed/unpulled commits, sync status
• Sort & Filter: Sort by name, status, or last activity; filter by text search
• Git Operations: Init git, pull, push, fetch for single or all repos
• GitHub Integration: Create private repos, archive repos (via gh CLI)
• Background Sync: Auto-fetch remotes every 5 minutes
• Caching: SQLite cache for fast subsequent runs

Installation

# From the gitforest directory
bun install

# Create config file
bun run start --init

# Edit config to add your project directories
vim ~/.config/gitforest/config.yaml

# Run gitforest
bun run start

Configuration

Config file location: ~/.config/gitforest/config.yaml

directories:
  - path: ~/projects
    maxDepth: 2
    label: Projects
  - path: ~/.dotfiles
    maxDepth: 3
    label: Dotfiles

scan:
  ignore:
    - node_modules
    - .git
    - vendor
  includeHidden: false
  concurrency: 5

github:
  defaultVisibility: private

display:
  showSubmodules: true
  sortBy: status # name | status | lastActivity
  sortDirection: desc

Keyboard Shortcuts

Navigation

| Key | Action | | --------- | ------------ | | j / ↓ | Move down | | k / ↑ | Move up | | g | Go to top | | G | Go to bottom |

Selection

| Key | Action | | ------- | ------------------------- | | space | Toggle selection | | a | Select all / deselect all |

Git Operations

| Key | Action | | --- | ------------------------------------- | | p | Push selected repos | | P | Pull all repos | | f | Fetch all remotes | | i | Init git in selected non-git projects |

GitHub Operations

| Key | Action | | --- | ------------------------------- | | c | Create GitHub repo for selected | | A | Archive GitHub repo |

View Controls

| Key | Action | | --- | -------------------- | | / | Enter filter mode | | s | Cycle sort field | | r | Refresh project list | | ? | Show help | | q | Quit |

Status Icons

| Icon | Meaning | | ---- | --------------------------- | | ✓ | Clean (no changes) | | ● | Dirty (uncommitted changes) | | ○ | Submodule | | - | Not a git repo | | ↑N | N unpushed commits | | ↓N | N unpulled commits |

Project Detection

Gitforest detects projects by looking for:

• .git directory (git repository)
• .gitmodules file (for submodules)
• Project marker files:
  • package.json (Node.js)
  • Cargo.toml (Rust)
  • pyproject.toml / setup.py (Python)
  • go.mod (Go)
  • Gemfile (Ruby)
  • pom.xml / build.gradle (Java)
  • And more...

Requirements

• Bun runtime
• gh CLI for GitHub operations (optional but recommended)

Development

# Run in development mode with hot reload
bun run dev

# Run tests (recommended - handles test isolation)
bun run test

# Or run specific test groups
bun run test:unit      # Unit tests only
bun run test:hooks     # Hooks tests (isolated)
bun run test:db        # Database tests (isolated)
bun run test:integration  # Integration tests

Architecture

src/
├── app.tsx                 # Root Ink application
├── config/                 # Config loading & validation (Zod)
├── db/                     # Drizzle + SQLite cache
├── git/                    # Git operations (Bun.$)
├── github/                 # GitHub CLI wrapper
├── scanner/                # Directory scanning
├── components/             # Ink UI components
├── hooks/                  # React hooks
├── state/                  # State management
└── types/                  # TypeScript types