So You Need to Fix a Broken Filesystem

R E P A I R S is a command-line filesystem recovery toolkit written in Rust. It targets ext4, NTFS, and XFS volumes that have become inconsistent after an unclean shutdown, power loss, or kernel panic. The project lives on GitHub and you can pull the latest release from the releases page. I've been running it against production volumes for about two years now, and it has saved me more times than I can count. Most people assume filesystem recovery means running a single command and walking away. It doesn't work that way. R E P A I R S breaks the problem into stages: it first maps the raw block layout, then identifies orphaned inodes and lost clusters, reconstructs directory trees where possible, and finally writes a corrected superblock and journal replay log. The output is either a repaired volume or a disk image you can inspect before committing changes. I should be blunt about something beginners get wrong. The tool does not guess. It reads metadata, cross-references checksums, and flags anything ambiguous. That's why the initial scan takes time. On a 4TB drive it typically runs for about forty minutes before it hands you a report. Don't interrupt it. I learned that the hard way on a server that had been rebooting every three hours because someone kept killing the process to "check progress."

Installation

The binary is distributed as a precompiled release for Linux x86_64 and aarch64. macOS and Windows builds exist but are community-maintained and sometimes lag behind the main repo. If you're on Debian or Ubuntu you can grab the .deb from the releases page, or build from source with Cargo. The source approach takes longer but gives you the option to compile with debug symbols if you need to file a bug report. That's it. No systemd service required. It's a CLI tool, not a daemon. Run it against a target device or image. Always against an image when you can. I run everything through a dd or dcfldd copy first, even if it means pulling the data off at night. Writing repairs directly to a live volume is possible but not recommended unless the alternative is letting the filesystem degrade further. The tool will refuse to run on a mounted volume by default, which is a good safeguard.

The three-command sequence is the standard pattern. The scan phase produces a JSON report detailing what it found. The reconstruct phase lets you review and tweak the proposed fix before anything is written. The apply phase executes it. Skipping the dry run is how people lose data they could have recovered. Last November I was working on an XFS volume that had suffered a dual-controller failure on a raid array. The metadata blocks were scattered across both disks, and when one controller came back online before the other, the filesystem showed a mixture of valid and corrupt directory entries. R E P A I R S flagged about 12,000 orphaned inodes but the reconstruct phase kept failing because it couldn't resolve a specific allocation group that had overlapping free space bitmaps. The workaround was to run the scan with the --ignore-allocation-group flag, which skips the problematic AG during reconstruction and marks those blocks for manual review afterward. It's not a ideal solution, but it let me recover about 94 percent of the directory structure. The remaining 6 percent turned out to be temporary build artifacts anyway, so the data loss was acceptable. I documented this in the issues tracker and the maintainer added a note about it in the next release's documentation.

Counter-Intuitive Things Nobody Tells You

First, running R E P A I R S on a drive that has been reformatted since the corruption happened is basically useless. The tool relies on residual metadata structures, and a format wipes those. People try it hoping for a miracle. It doesn't work. The tool needs the original filesystem geometry to remain intact, even partially. Second, the size of your journal matters more than you'd think. On ext4 volumes with a small journal (usually 64MB or less), R E P A I R S has less to work with during replay. Larger journals give the tool more transaction history to trace back through, which improves recovery accuracy. If you're setting up a new volume and anticipate potential corruption, allocate a 256MB journal. It costs nothing extra and makes recovery significantly more reliable. Third, the tool's "recovery rate" numbers on the website are measured on clean test cases. Real-world recovery depends heavily on how long the filesystem sat in a corrupted state before you ran the tool. Every hour of continued writes degrades the odds. I've seen recovery rates drop from 97 percent to about 40 percent on volumes that were left unread for a week while someone debated whether to run the tool.

Known Limitations

R E P A I R S does not handle ZFS, Btrfs, or APFS. If you're running one of those, you need different tooling. The XFS module is the most mature but still has edge cases around sparse files larger than 100GB. I've seen it misidentify sparse file extents as data, which causes the reconstruct phase to propose incorrect block allocations. The workaround is running the scan with --verify-extents enabled, which adds about twenty minutes to the scan but catches those misreads. Another limitation: the tool assumes the underlying block device is stable. If you're recovering from a drive that has physical bad sectors, R E P A I R S will either stall or produce incorrect results. In that scenario you need to map the bad sectors first using smartctl or a dedicated SMART analysis tool, then create a sector-level image that skips the damaged regions before feeding it into R E P A I R S. The CLI output is minimal. There's no progress bar during the scan phase, just a single line that says scanning and a timestamp. It looks like it hung. It hasn't. This frustrates people who are watching a terminal for six hours wondering if the process crashed. There's a --verbose flag that prints periodic progress updates, but it significantly increases I/O overhead and slows the scan down by about thirty percent. Use it only if you need reassurance.

Alternatives Worth Knowing

For ext4 specifically, e2fsck is the built-in option and it's often sufficient for minor corruption. R E P A I R S shines when e2fsck gives up or produces incomplete results. For NTFS, chntpw and ntfsfix handle simple cases, but R E P A I R S goes deeper with journal reconstruction. If you're dealing with a hardware-level drive failure rather than filesystem corruption, none of these tools will help you. You need a professional data recovery service with a cleanroom setup. Download the tool from the official GitHub releases page. Read the documentation before running it against anything important. The margin between recovering a volume and making it worse is usually a skipped dry run.