Live Application: dazzo31.github.io/gitunstuck
Guiding Principle: Don't Panic. Git almost never loses your committed work.
Sponsor:
GitUnstuck is an empathetic, interactive problem-solving guide and diagnostic cheatsheet designed to help developers recover from Git mistakes, navigate cloud platform rejections across GitHub, GitLab, and Bitbucket, and master Git's mental model without cognitive overload.
- Guided Essentials Mode: Focused, approachable view emphasizing plain-English analogies, daily routines, and zero-jargon recovery steps. Complex mathematical graph theory is automatically hidden from the beginner primer.
- Developer Hub Mode: Expands the complete Git engineering reference, including interactive rebasing, branch divergence surgery,
git worktreeisolation,git reflogresurrection, and live.git/filesystem inspectors. - Dynamic Mode Theming: Active mode seamlessly shifts UI iconography, borders, and active tokens to organic emerald green (Guided Essentials) or energized amber orange (Developer Hub).
- Integrated custom, lightweight 1.5px stroke vector SVG icons across all analogy cards, recipe controls, and forge selectors for consistent visual elegance without external font or asset overhead.
- Deployed bespoke standalone responsive SVG Wordmark (
gitunstuck-wordmark-dark.svg,gitunstuck-wordmark-light.svg), single calligraphic 'G' app icon, and multi-theme adaptive favicons with full screen-reader accessibility (sr-onlytitles).
- Integrated native GitHub Sponsors (
.github/FUNDING.yml), a dedicated header Buy Me a Coffee pill button, and footer learning resource support cards.
- Modernized light mode code blocks with dedicated soft slate backgrounds (
--bg-code) and high-contrast dark text, eliminating all low-contrast artifacts in terminal textareas and.git/files inspectors.
- Interactive architectural simulation tracing file lifecycles across Working Directory (Disk) → Staging Area (Index) → Local Repository (HEAD) → Remote Cloud (Forge). Features click-to-inspect cards, terminal output previews, copyable forward/rollback commands, and the complete two-way highway.
- Test automation expanded to 155 passing unit assertions across 13 suites, verifying input normalization, token injection, multi-host forge rules, brand identity tokens, experience mode toggles, and the 4-Zone data flow engine.
When something breaks, beginners often panic fearing total code loss. The top of GitUnstuck now features:
- Instant Intent Chips: One-click shortcuts for the top 6 panic scenarios (
Undo a mistake,Push was rejected,Merge conflict,Detached HEAD,Auth failed,Lost work / commit). - The Golden Safety Bookmark: A prominent 1-second safety recipe (
git branch backup-before-fix) guaranteeing you can always return to your current state before attempting any rewrite.
- Privacy-First (100% Client-Side): Paste output from
git status,git status -sb, or raw terminal error messages. Input is never transmitted over the network or uploaded anywhere. - Input Sanitizer: Automatically strips ANSI color escapes and normalizes Windows CRLF line endings.
- 12-State Rule Engine: Automatically diagnoses Detached HEAD, Merge Conflicts, Paused Rebases, Branch Divergence, Untracked Sensitive Files (
.env,id_rsa), GH013 Secret Scan blocks, Protected Branch rejections, and Authentication failures. - "Is My Work Lost?" Indicators: Every diagnosis explicitly answers the #1 anxiety question upfront (
🟢 Work is Safevs⚠️ Permanent Loss Risk). - 1-Click Test Samples: Built-in sample buttons (
Detached HEAD,Merge Conflict,Diverged Branch,Secret Scan,Clean Status) allow users to test the diagnostic engine instantly.
Platform-specific troubleshooting tabs covering the real-world divergence points between cloud providers:
- Protected Branch Rejections: GH006 protected branch updates, GitLab protected branches, and Bitbucket branch permissions — with verified feature-branch + PR/MR creation workflows.
- Authentication & Credential Caching: GitHub Personal Access Tokens (and the fine-grained
workflowscope caveat), GitLab PATs and firewall port 443 fallback (altssh.gitlab.com:443), and Bitbucket Cloud's critical requirement to use the Atlassian Account Email with App Passwords. - Push Protection Secret Scanning: Handling GitHub GH013 and GitLab secret blocks via soft-resets and
.gitignoresanitization. - Fork Synchronization: Syncing upstream remotes via web shortcuts and terminal commands.
Select where your unwanted changes currently live:
- Unstaged in File:
git restore <file>(Destructive risk warning) - Staged in Cart:
git restore --staged <file>(100% safe, preserves disk edits) - Committed Locally:
git reset --soft HEAD~1(Safe, rewinds checkpoint while keeping work in cart) - Pushed to Remote:
git revert <commit-id>(Team-safe inverse commit) - Lost Commit / Deleted Branch:
git reflog -n 15+git switch -c rescue-branch(Local ledger resurrection)
Interactive SVG visualization demonstrating how commits, branch labels, HEAD (your camera lens), and merge operations interact in real time.
- Surface Level: Real-world analogies (Shopping Cart, Video Game Save Point, Breadcrumbs) and zero-jargon daily workflows.
-
Deep Level: Formal Computer Science Directed Acyclic Graph ($G=(V, E)$), SHA cryptographic object stores, and LCA 3-way merge matrix theories neatly organized in accessible
<details><summary>drawers.
Every major resolution and workflow supports direct URL hash deep-linking for easy sharing in team chat:
#emergencyHero— Jump to emergency triage hero#troubleshootConsole— Jump to the Undo Decision Tree#terminalAnalyzer— Jump to the live terminal paste analyzer#card-forge-troubleshoot— Jump to Cloud Forge Troubleshooter#forge-github,#forge-gitlab,#forge-bitbucket— Pre-select specific cloud hosts#undo-unstaged,#undo-staged,#undo-local-commit,#undo-pushed-commit,#undo-lost-reflog— Direct decision tree solutions#card-init,#card-clone,#card-stage,#card-branch,#card-sync,#card-conflict,#card-rebase,#card-detached,#card-reflog— Direct workflow cards
GitUnstuck includes an automated diagnostic test suite verifying input normalization, rule matching, and forge coverage:
# Run the automated test runner (155 passing unit tests across 13 suites)
node tests/test-analyzer.js- Zero Dependencies: Pure vanilla HTML5, CSS3, and modern JavaScript.
- Zero Build Step: Deploys instantly to GitHub Pages directly from repository files.
- Zero Data Transmission: Complete privacy guarantee — user repository paths, branch names, and code snippets stay strictly inside the client's browser tab.
- Accessible (WCAG AA): High-contrast dark and light modes, full keyboard navigation (
/andCtrl+Ksearch shortcuts), reduced-motion support, and screen reader announcements.
GitUnstuck was built to make Git mental models intuitive and save developers from hours of panic and lost work. It is 100% free, private, client-side, and ad-free.
If this guide helped you master a workflow, rescued your branch, or saved your team time, consider sponsoring ongoing development:
MIT License. Free for developers, students, and teams worldwide.