Why RapidForge Git?

Git is powerful, but it isn't always friendly. Two problems come up again and again:

• Multi-account chaos. If you use separate GitHub accounts for work and personal projects, HTTPS credential caching makes it easy to accidentally push under the wrong identity - and fixing that usually means digging through SSH configs.
• Fear of the command line. Commands like git reset --hard are unforgiving. One typo or one misunderstood flag can undo hours of work.

RapidForge Git solves both. It's a zero-configuration, interactive terminal UI (TUI) that turns Git's state and workflows into a visual dashboard with guided, numbered menus - so you always know what's about to happen before it happens.

Table of Contents

• Installation
• Getting Started
• RapidForge vs. Traditional Git
• Features
  • The Dashboard (HUD)
  • Guided Workflows
  • Automated SSH Wizard
  • Safe Undo
• System Requirements
• Troubleshooting
• Contributing
• License

Installation

Install the package globally with npm:

npm install -g rapidforge-git

Verify the install:

rf --version

Getting Started

Navigate to any Git repository and launch the dashboard:

cd your-project
rf

That's it - no config files, no setup step required. RapidForge Git detects your repository automatically and opens straight into the dashboard.

RapidForge vs. Traditional Git

| Task | Traditional Git | RapidForge Git | |---|---|---| | Check repo status | git status + git log + git branch (three commands) | One glance at the dashboard | | Update branch with remote | git fetch + git status + git pull | Choose Fetch & Pull from the main menu | | Commit and push | git add . && git commit -m "msg" && git push | Choose Push Code, follow the prompts | | Set up a second GitHub account | Manually generate SSH keys, edit ~/.ssh/config, debug 403 errors | Run the SSH Setup Wizard | | Undo the last commit | git reset --soft HEAD~1 (easy to get wrong) | Choose Undo Changes → Undo last commit |

Features

1. The Dashboard (HUD)

The moment you run rf, you see everything that matters about your repository at a glance:

• Branch status - your current branch, and whether it's ahead of, behind, or in sync with the remote.
• Working tree summary - live counts of staged, modified, and untracked files.
• Latest commit - the short hash and message of your most recent commit.

No need to run three separate commands and mentally piece the picture together.

2. Guided Workflows

Every common Git task is one numbered menu choice away:

• Fetch & Pull - Safely check if your local branch is behind the remote and pull the latest changes interactively.
• Push Code - stages, commits, and pushes in a single guided flow. If it detects you're on an unsafe HTTPS connection, it offers to upgrade you to SSH automatically.
• Clone Repository - pick an SSH identity from your saved configs, enter a repo name, and clone securely without touching the command line.
• Branch Management - list, create, switch, and delete branches without needing to remember git checkout -b or git branch -D.
• Safe Undo - see below.
• Fast Navigation - Press 0 at any time to instantly exit the dashboard or go back to the previous menu.

3. Automated SSH Wizard

Juggling a work account and a personal account on GitHub usually means manually generating keys and editing SSH config files. RapidForge Git automates the whole process. Just provide an email and a short alias, and it will:

1. Generate a modern ed25519 SSH keypair.
2. Add the correct entry to your ~/.ssh/config file.
3. Convert the current repository's remote URL from HTTPS to SSH.
4. Copy your new public key to the clipboard and open GitHub's SSH settings page in your browser, ready to paste.

4. Safe Undo

A dedicated menu for reversing mistakes without gambling with flags you don't fully remember. Each option tells you plainly what it will and won't affect - for example, distinguishing between undoing a commit (keeps your file changes) and discarding changes (removes them), so you're never surprised by the result.

System Requirements

• Node.js v16 or higher
• Git, installed and available on your system PATH

Troubleshooting

Windows: PowerShell blocks the command with "running scripts is disabled"

Cause: PowerShell's default execution policy blocks locally installed npm scripts from running.

Solution: Open PowerShell as Administrator and run:

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

Confirm with Y when prompted, then close and reopen PowerShell and try rf again.

If you'd rather not change your execution policy, run RapidForge Git from Git Bash or Command Prompt instead - this restriction doesn't apply there.

"rf: command not found" after installing

Cause: Your global npm bin directory isn't on your system PATH, so the shell can't find the rf executable.

Solution:

1. Find your npm global prefix:

   npm config get prefix

2. Confirm the package is actually installed there:

   npm list -g rapidforge-git

3. Add the bin folder inside that prefix to your shell's PATH:
   • macOS/Linux (bash/zsh): add this line to ~/.bashrc or ~/.zshrc, then restart your terminal:

     export PATH="$(npm config get prefix)/bin:$PATH"

   • Windows: add the prefix path to your Environment Variables → Path via System Properties, then restart your terminal.
4. Run rf --version to confirm it now works.

SSH Wizard fails to connect to GitHub

Cause: The new SSH key hasn't been added to your GitHub account yet, or the wrong key is being used for the connection.

Solution:

1. Confirm the key was generated: check for a new keypair in ~/.ssh/ (for example id_ed25519_<alias>).
2. Confirm it was added to GitHub: go to GitHub → Settings → SSH and GPG keys and check that the key from your clipboard was pasted and saved.
3. Test the connection directly:

   ssh -T [email protected]<alias>

   (use the host alias RapidForge Git created in your ~/.ssh/config)
4. If it still fails, verify the Host entry in ~/.ssh/config points to the correct IdentityFile path.

Push fails with a permissions or 403 error

Cause: You're pushing over HTTPS with cached credentials for the wrong GitHub account.

Solution: Run Push Code from the dashboard - RapidForge Git detects the unsafe HTTPS connection and offers to switch the remote to SSH automatically. If you'd rather fix it manually, run the SSH Setup Wizard first, then retry the push.

Contributing

Issues and pull requests are welcome. If you're proposing a larger change, please open an issue first to discuss what you'd like to add or change.