# 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](https://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?

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

## Usage Questions

### How do I start Forge?

```bash
# 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:

```bash
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:

```bash
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:

```bash
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:

```bash
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](https://github.com/Princelad/forge/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](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](https://github.com/Princelad/forge/issues) or ask in Discussions.