FAQ

FAQ

General Questions

What is Forge?

Forge is a terminal-based Git-aware project management system. It lets you manage Git repositories, view diffs, track tasks, and collaborate with team members all from your terminal without breaking your coding flow.

Why use Forge instead of Git CLI or GitHub?

• Integrated workflow — Git operations + project management in one TUI
• Visual context — See diffs, branches, and project status side-by-side
• Keyboard-driven — Designed for developers who live in the terminal
• No context switching — Everything you need without tabs/windows

Is Forge production-ready?

Not yet. Forge validates a design concept for Git-integrated project management. Core features work well, but some advanced features are still in development.

Can I use Forge with my existing Git workflow?

Yes! Forge works with any existing Git repository. It reads from and writes to Git normally—you can continue using your usual Git commands alongside Forge.

Installation & Setup

Do I need to install Git separately?

Yes, Forge requires Git 2.0+ to be installed on your system. Install via:

• macOS: brew install git
• Ubuntu/Debian: sudo apt-get install git
• Windows: Download from git-scm.com

Can I use Forge on Windows?

Yes, but terminal support varies. Use Windows Terminal for best results. Cygwin or WSL2 also work.

What terminals are supported?

Any terminal with 256-color support works well:

• macOS: Terminal.app, iTerm2, Alacritty
• Linux: Gnome Terminal, Konsole, Alacritty, xterm
• Windows: Windows Terminal, ConEmu

How do I update Forge?

cd /path/to/forge
git pull origin main
cargo build --release
cp target/release/forge ~/.local/bin/

Usage Questions

How do I start Forge?

# Navigate to a Git repository
cd /path/to/your/repo

# Run Forge
forge

Why does Forge say "No Git repository found"?

Forge looks for a .git folder. If you're in a non-Git directory:

git init                # Initialize a new repo
# or
cd /path/to/git/repo    # Navigate to an existing repo

How do I stage and commit files?

1. Go to the Changes screen (Tab navigation)
2. Use arrow keys to select files
3. Press Space to toggle staging
4. Type a commit message
5. Press Enter to commit

What if I make a mistake in a commit?

Use standard Git commands:

git reset --soft HEAD~1     # Undo last commit, keep changes staged
git revert HEAD             # Create a new commit that undoes changes
git amend                   # (if using Git 2.32+) Amend last commit

Can I push/pull from Forge?

Not yet. Remote operations (push, pull, fetch) are not yet implemented. Use the Git CLI for now:

git push origin main
git pull origin main

How do I resolve merge conflicts?

1. Go to Merge Visualizer screen
2. Use arrow keys to select conflicted files
3. View local and incoming versions side-by-side
4. Press Space to mark as resolved
5. Use Git CLI to finalize: git merge --continue

Can I customize keybindings?

Not yet. Keybindings are currently hardcoded. Future versions will support custom configuration.

Project Board Questions

How do I create a module?

1. Go to Project Board
2. Press n to create new module
3. Enter module name and details
4. Press Enter to save

How are developers auto-populated?

Developers are extracted from Git commit history automatically. Each unique commit author is added as a developer.

Can I manually add developers?

Yes, go to Module Manager and press n to create a new developer manually.

What does the progress percentage mean?

Progress is a 0-100% indicator for module completion. Set manually based on actual development status.

How is data persisted?

• Modules & Developers: .forge (JSON file in repo root)
• Merge tracking: .git/forge (JSON file in Git directory)
• Settings: System configuration (theme, preferences)

Troubleshooting

Forge crashes on startup

• Check terminal size (minimum 80×24 characters)
• Ensure you're in a valid Git repository
• Try updating Rust: rustup update
• Check for large repositories (>100MB history may be slow)

Keybindings not responding

• Press ? to see available keybindings for current screen
• Some terminal emulators don't support certain key combinations
• Try a different terminal if issues persist
• Check that your terminal is in focus

Diff preview not showing

• Ensure the file is modified (check with git status)
• Try selecting a different file and back
• Verify terminal has enough columns to display diff

Settings not saving

• Check permissions on .forge file
• Ensure you're in a writable directory
• Try deleting .forge and restarting Forge

Terminal text is garbled

• Your terminal may not support 256 colors
• Try a different terminal emulator
• Disable High Contrast theme in settings

"Fatal: No HEAD" error

• Your repository may be empty or corrupted
• Try: git status to verify repo health
• If corrupted, consider cloning from remote

What happens if my Git repository is corrupted?

Current Behavior:

Forge uses libgit2 for all Git operations and will display errors when corruption is detected:

• Missing/corrupted HEAD: Branch name may show as empty, some operations will fail
• Corrupted index: File staging, commits, and change listing will fail with error messages
• Missing objects: Diffs may appear empty or operations may fail
• Locked index: Operations fail if .git/index.lock exists (another Git process running)

Recommended Actions:

1. Check repository health: Run git fsck in a terminal to diagnose corruption
2. Remove index lock: If operations fail with "index is locked", remove .git/index.lock
3. Rebuild index: Run git read-tree HEAD to rebuild a corrupted index
4. Restore from backup: For severe corruption, clone from remote or restore from backup
5. Use standard Git: Forge doesn't currently auto-repair repositories (see Roadmap)

Prevention:

• Don't force-quit Forge during commit operations
• Avoid running multiple Git clients simultaneously on the same repo
• Keep repository backups and push to remotes regularly

Future Improvements (Planned - see Roadmap):

• Repository health check on startup
• Automatic detection and repair of common index corruption
• Graceful degradation (read-only mode when index is corrupted)
• Better error messages with actionable recovery steps

Performance & Optimization

How can I speed up Git operations?

• Shallow clone large repos: git clone --depth 1
• Use more powerful hardware for large repositories
• Exclude large files from staging

What's the maximum repository size Forge handles?

Forge works with repositories of any size, but very large histories (>10,000 commits) may show slower performance. The commit history view limits to last 50 commits to maintain responsiveness.

Does Forge use a lot of disk space?

No, Forge doesn't cache data locally. It reads from your existing Git repository.

Data & Privacy

Where is my data stored?

• Git data: Standard Git repository (.git folder)
• Forge metadata: .forge JSON file in repo root
• No data is sent to external servers

Is my data secure?

Forge doesn't add any security features beyond Git itself. If your Git repository is secure, your Forge data is secure.

Can I delete Forge data?

Yes:

rm .forge                 # Delete module/developer data
rm -rf .git/forge         # Delete merge tracking data

Contributing

How do I report a bug?

Open an issue on GitHub Issues with:

• Steps to reproduce
• Expected vs actual behavior
• Terminal/OS information

How do I suggest a feature?

Open a discussion or feature request on GitHub.

Can I contribute code?

Yes! See the Development guide for contribution workflow.

Advanced Questions

Can Forge work with multiple branches simultaneously?

Not yet. Forge works with your current branch. Switch branches using the Branch Manager.

Does Forge support Git hooks?

Forge executes Git normally, so Git hooks run as expected.

Can I use Forge with monorepos?

Forge treats the entire repository as one unit. For monorepos, it shows all modules and developers across the entire codebase.

---

Can't find your answer? Open an issue on GitHub Issues or ask in Discussions.