.git/worktrees/recovery-reference.md is created automatically when you run your custom git recover alias.
This file acts as your personal, project-specific recovery playbook, tied directly to your repo’s Git history but never committed to shared remotes, so you can adjust its contents to match your workflow without cluttering project history for any future collaborators. The habits outlined below ensure you never lose hours of work to a bad commit, accidental hard reset, or untested WIP push that breaks core functionality for your users.
Identify the broken line
The broken line is the exact point in your Git history where working, tested code stops and broken, untested code begins. For solo projects, this is almost always the commit right before you merged an untested WIP branch to main, or the third of three quick commits you pushed to your feature branch while you were tired and not running tests. You can spot it immediately if you follow the habit of tagging every production-ready main commit with a sequential, dated tag like v1.2.20240516, so you don’t have to scroll through 40 commit messages with titles like “fix” or “update” to find the last working state. Illustrative example: 72% of solo devs who tag every production-ready main commit spend less than 10 minutes resolving accidental breakage, compared to 21% who only tag major releases with new feature sets. When you identify the broken line, you write its commit hash and a short note about what broke (e.g., “commit a72f9b broke checkout flow after adding discount code logic”) to your recovery reference file before you make any changes to your repo state. This practice ensures you don’t lose track of the root cause mid-recovery, even if you get distracted or need to step away from the project for a few hours.
Preserve unmodified baselines
This step locks down the stable parts of your repo to avoid making a bad situation worse. First, you never modify the main branch directly during recovery: all changes happen in temporary, explicitly named branches so you can abandon them if you make a mistake without touching your single source of truth. Second, you never delete your broken WIP branch, even if you think it’s unsalvageable: you rename it to something like w/broken-checkout-flow-20240516 and leave it in your local repo for 30 days, so you can pull individual working commits from it later if you need to. Third, you never edit or delete existing production tags, even if you think they’re outdated: those tags are your immutable recovery points, and altering them removes your fastest path back to a working state if your recovery attempt fails. You also leave your global Git config untouched during recovery, so you don’t accidentally enable force pushes to main or turn off safety checks that prevent you from erasing history. Even if you’re certain you know what caused the bug, preserving baselines first gives you a guaranteed escape hatch if your initial recovery plan doesn’t work.
Execute targeted recovery edits
This step follows a strict, repeatable 4-step process that relies only on safe, non-destructive Git commands that leave your full history intact:
- Pull the latest main branch to your local environment, then check out the most recent working production tag (you tagged this commit before pushing your last working main update, so you don’t have to sift through reflog to find it) to enter a detached HEAD state that won’t alter existing branch history.
- Run `git branch -c temp-recovery` to create a temporary recovery branch off the working tagged commit, then cherry-pick only the non-breaking commits from your WIP feature branch that you want to retain, skipping the three commits that introduced the bug.
- Run `git revert –no-edit [hash of first bad commit] [hash of second bad commit] [hash of third bad commit]` to generate explicit, auto-documented revert commits that clearly mark exactly what code you are rolling back, no ambiguous reset commands that erase history.
- Apply the uncommitted WIP changes you stashed before starting recovery with `git stash apply`, resolve any minor merge conflicts, and test the full core flow end-to-end to confirm the bug is resolved before moving further.
Once you confirm the code works, you merge the temp-recovery branch to main, push the updated main branch and a new production tag to your remote, and delete the temporary recovery branch. This process ensures you never lose any work, even if you decide to revisit the broken feature later.
Store the reference file correctly
Your .git/worktrees/recovery-reference.md file lives in the .git/worktrees directory for a specific reason: all content inside the .git directory is ignored by default, so it will never be committed to your repo or synced to remote hosts, even if you accidentally run `git add .` in your project root. You add a new entry to this file every time you complete a recovery, including the broken line commit hash, the working tag you used as a baseline, the exact revert commands you ran, and a short note about what caused the bug so you can avoid the same mistake in the future. You can also add copies of your custom Git aliases for recovery, tagging, and branch creation to this file, so you don’t have to look up your global config when you’re working on a new machine or troubleshooting while traveling. If you work on multiple solo projects, you can sync a generic version of this file across your devices with a personal cloud drive, but always keep project-specific entries tied directly to the repo they belong to to avoid confusion between codebases.
Exclude high-risk entries
This step keeps your recovery flow safe by leaving out anything that could cause data loss or security risks. First, you never add force push aliases that default to pushing to main to your recovery playbook: force pushes should always require explicit, manual target definition, so you don’t accidentally overwrite remote main history when you’re panicking mid-breakage. Second, you never add hard reset commands to your standard recovery flow, even for WIP branches: if you need to reset a branch, you always create a backup copy of the branch first with `git branch -c backup/[branch-name]-[date]` so you can restore it if needed. Third, you never add sensitive credentials like personal access tokens, API keys, or database passwords to your recovery reference file, even though it’s stored in the ignored .git directory: if you ever zip up your full repo to share with a collaborator or debug a remote issue, you don’t want to accidentally expose sensitive data. Fourth, you never add vague notes like “fixed the bug” to your reference entries: always include specific commit hashes, tag names, and command snippets so you can replicate the recovery flow exactly if the same bug pops up again 6 months from now.
The next time you open this file
When you open .git/worktrees/recovery-reference.md next, you’ll be facing a new break in your code, and the first thing you’ll do is cross-reference the current error message and broken commit hash against your existing log of past recovery entries. You’ll be able to pull the most recent working tag in seconds, spin up a temporary recovery branch, run the same structured revert steps you’ve documented here, and get back to building new features in minutes instead of spending hours digging through reflog, searching generic Git fixes, or rewriting hours of lost work. Over time, this file will grow into a custom playbook tailored exactly to your project’s unique failure points, your coding habits, and your preferred workflow, so you never have to waste time troubleshooting the same issue twice. This workflow aligns with the low-friction, high-reliability solo dev frameworks shared on Build Next Stack for keeping side projects maintainable long term, no complex team Git processes required to keep your work safe and recoverable. You’ll also be able to use the patterns you document here for all future solo projects, cutting down on recovery time for every new codebase you build.