GitForge Documentation

Setup guides, configuration references, and everything you need to get your Forge up and running.

1. Getting Started

GitForge is a cross-platform Git client available on Android, macOS, Windows, and Linux. Here's how to go from install to your first commit.

Quick Start

1. Install GitForge — Download from the Downloads page for your platform.
2. Add an SSH Key — Go to Settings → SSH Keys and import your private and public key files. GitForge only supports SSH URLs (e.g. git@github.com:user/repo.git).
3. Create a Git Identity — Go to Settings → Git Identities and add your name and email. This is the author info attached to your commits.
4. Clone a Repository — Tap the + icon in the Navigator's FORGES section (or the "Clone Repository" button on the Home screen). Enter your SSH URL, select your SSH key, and optionally assign it to a Smithy and Git identity.
5. Start Forging — Edit files in your IDE, then use the Anvil panel to stage, review diffs, and commit.

2. SSH Keys

SSH keys are how GitForge authenticates with remote Git servers. You can manage them in Settings → SSH Keys.

Adding a Key

1. Give the key a name (e.g. "github", "work-gitlab").
2. Import the private key content — either paste it or use the file picker to select your id_ed25519 or id_rsa file.
3. Import the public key content — same process, using your .pub file.
4. If your key has a passphrase, enter it. Leave empty if none.

Both Ed25519 and RSA key formats are supported. When cloning, select the key to use from the SSH Key dropdown. You can also bind a default SSH key to a specific repository after cloning.

Custom SSH Hosts

GitHub, GitLab, and Bitbucket host keys are pre-loaded. For self-hosted Git servers (e.g. a company GitLab instance), go to Settings → Custom SSH Hosts:

• Auto-Scan: Enter the hostname (e.g. gitlab.company.com) and GitForge will scan for the host key automatically.
• Manual Paste: Run ssh-keyscan your.server.com on your computer and paste the output into the text field.

3. Git Identities

A Git identity is the name and email that appear on your commits. Manage them in Settings → Git Identities.

• Default Identity: Set one identity as your default. It will be used for all repos that don't have a specific override.
• Per-Repo Override: On any repository's detail screen, you can assign a different identity. This is useful when you use a personal email for open-source and a work email for company repos.
• Clone-Time Selection: When cloning a new repo, you can choose which identity to attach from the clone screen dropdown.

4. Forge Sync (Zero-Knowledge)

Forge Sync lets you synchronize your workspace across all your devices — phone, laptop, desktop — with zero-knowledge encryption. Set it up in Settings → Cloud Sync.

Setting Up Sync

1. Register with your email. A Sync Key is generated on your device — save it somewhere safe. This key is your encryption passphrase and cannot be recovered if lost.
2. On additional devices, choose Connect Existing and enter your email + Sync Key.
3. Sync triggers immediately when you make changes (save a key, clone a repo, level up your pet, etc.), plus a background sweep every 5 minutes and whenever the app regains focus.

What Gets Synced

• Smithies & Forges: Project structure and repository metadata (URLs, branch associations, SSH key bindings).
• SSH Keys: Private and public key content, encrypted. Toggle on/off in sync settings.
• Git Identities: All your name/email pairs.
• AI API Keys: Gemini and Claude API keys. Toggle on/off in sync settings.
• .env Files: Environment files in your repos, encrypted. Toggle on/off.
• Blueprints & Diagrams: .gitforge/blueprint.yaml and all .gitforge/diagrams files, plus AI context files (GEMINI.md, CLAUDE.md).
• Pet Data: Your companion's level, XP, stats, abilities, and items.
• User Settings: AI provider selection, model preferences, and sync toggles.

Repos that are synced but not yet cloned on a device appear as "Unlit Forges" in the Navigator. Tap one to start a one-tap clone with all the metadata (SSH key, identity, Smithy) pre-filled.

5. AI Commit Messages

GitForge can generate commit messages from your staged changes using the Gemini or Claude API. Configure in Settings → AI Forging.

Configuration

1. Choose your AI Provider: Google Gemini or Anthropic Claude.
2. Enter your API Key for the selected provider.
3. Select a Model:
   • Gemini: 2.5 Flash (Stable), 2.5 Pro (Flagship), 2.5 Flash-Lite (Eco), 3 Flash (Preview)
   • Claude: Sonnet 4.6 (Latest), Opus 4.6 (Strongest), Sonnet 4 (Stable)

Once configured, click the ✨ sparkle icon next to the commit message box in the Anvil panel. The AI will analyze your staged diff and generate a commit message. You can edit it before committing.

6. The Desktop Workspace

On desktop (macOS, Windows, Linux), GitForge provides a multi-pane workspace with the following panels:

• Navigator (Left): Browse Smithies, Forges, branches, and stashes. Shows dirty indicators (orange dot) and terminal activity (green icon).
• Center Tabs: Switch between the Timeline (commit graph), Diff Viewer (side-by-side), README, and Drafting Board.
• Anvil (Right): The staging panel. Files flow from Raw Materials (unstaged) → On the Anvil (staged) → Strike the Hammer (commit).
• Terminal (Bottom): Native PTY terminal sessions scoped per-repo. Supports multi-tab. Uses your system's default shell.

All panels are resizable via drag handles. The layout automatically persists between sessions.

7. Forge Glossary

GitForge uses a blacksmith theme across its UI. Here's a quick reference:

8. Platform Notes

Android

• All Git operations (clone, commit, push, pull, branch, diff, stash) run directly in-app on any supported Android device.
• GitForge does not include a built-in terminal on Android. For AI CLI workflows, use the Copy Path button in the app to grab your forge or smithy directory path, then open the Linux Terminal app separately and navigate to it.
• The Linux Terminal app requires Android 16+ and is currently available on Pixel 8 and newer (some Samsung devices also support it).
• All AI context files — Blueprints, Mermaid diagrams, GEMINI.md, CLAUDE.md, and .env files — are synced to the same directory that the Linux Terminal can access. Your AI CLIs will have full context even though they run outside GitForge.

macOS / Windows / Linux

• Full multi-pane desktop workspace with resizable panels.
• Native PTY terminal sessions using your system's default shell (reads $SHELL, defaults to /bin/zsh).
• Repos default to ~/Documents/ForgeRepos (configurable in Settings).