Skip to content

Commit 9958d24

Browse files
PabloLecPabloLec
committed
Edit README
1 parent db03a06 commit 9958d24

1 file changed

Lines changed: 88 additions & 50 deletions

File tree

‎README.md‎

Lines changed: 88 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -1,112 +1,150 @@
11
<div align="center">
22
<img src="docs/assets/logo.png" alt="RecoverPy" width="auto">
33
<h2>RecoverPy</h2>
4-
<em>Find and recover deleted or even overwritten files from your Linux partitions, quickly and easily.</em>
5-
6-
<br><br>
4+
<em>Scan raw partitions and recover data by inspecting disk blocks directly.</em>
75

6+
<br><br>
87
![GitHub release](https://img.shields.io/github/v/release/pablolec/recoverpy?style=flat-square)
98
![License](https://img.shields.io/github/license/pablolec/recoverpy?style=flat-square)
109
![Downloads](https://static.pepy.tech/personalized-badge/recoverpy?period=total&units=abbreviation&left_color=grey&right_color=red&left_text=downloads)
1110
![Tests](https://github.com/PabloLec/recoverpy/actions/workflows/pytest.yml/badge.svg?branch=main)
12-
1311
</div>
1412

1513
---
1614

17-
RecoverPy doesn't just recover deleted files, but also helps you **recover overwritten data** by scanning each disk block. Whether it's a lost snippet of code, accidentally deleted configs, or overwritten text files, RecoverPy gives you a powerful, interactive way to get it back.
18-
19-
## ✨ Features
20-
21-
- ✅ Recover **overwritten and deleted files**
22-
- 🔍 Search file contents by string, even in binary files
23-
- 📟 Modern, easy-to-use terminal UI
24-
- 🐧 Linux compatible (all file systems supported)
25-
- ⚡️ Fast, leveraging core Linux utilities (`grep`, `dd`, `lsblk`)
26-
27-
---
28-
2915
## 🎬 Demo
3016

3117
<p align="center">
3218
<img src="docs/assets/demo.gif" alt="RecoverPy Demo">
3319
</p>
3420

21+
## 🔎 Overview
22+
23+
When a file is deleted, its metadata disappears first. The underlying disk blocks often remain intact until they are reused.
24+
25+
RecoverPy scans raw partition data directly and searches for byte patterns across the entire device. If the blocks have not been overwritten, fragments of deleted files can still be located by their content.
26+
27+
It lets you inspect matching blocks, navigate adjacent ones, and extract what remains in a straightforward way.
28+
29+
If the blocks are gone, recovery is impossible. If they are still there, RecoverPy helps you retrieve them.
30+
3531
---
3632

37-
## 📦 Installation
33+
## 🧭 What you can do
3834

39-
> **Warning:** You **must** run RecoverPy as root (`sudo`).
35+
* Search a partition or disk image for a specific string.
36+
* Inspect the disk blocks where matches are found.
37+
* Move across adjacent blocks to recover fragmented data.
38+
* Select and save useful content.
4039

41-
RecoverPy is Linux-only. Make sure you have these common tools installed (`grep`, `dd`, `lsblk`). Optionally, install `progress` to monitor scan progress:
40+
RecoverPy does not attempt to interpret filesystem structures or restore filenames. It focuses on exposing what remains on disk and making it accessible.
4241

43-
```bash
44-
# Debian / Ubuntu
45-
sudo apt install grep coreutils util-linux progress
42+
---
4643

47-
# Arch
48-
sudo pacman -S grep coreutils util-linux progress
44+
## 📦 Installation
4945

50-
# Fedora
51-
sudo dnf install grep coreutils util-linux progress
52-
```
46+
### Requirements
5347

54-
### Quick Run (no installation)
48+
- Linux
49+
- Python 3.9+
5550

56-
Using `pipx`:
51+
Accessing raw block devices typically requires `sudo`.
52+
53+
### Using `uv`
5754

5855
```bash
59-
sudo pipx run recoverpy
60-
```
56+
sudo uvx recoverpy
57+
````
6158

62-
Or using `uvx`:
59+
Or install locally:
6360

6461
```bash
65-
sudo uvx recoverpy
62+
uv tool install recoverpy
63+
sudo recoverpy
6664
```
6765

68-
### Install from PyPI
66+
### Using pip
6967

7068
```bash
71-
python3 -m pip install recoverpy
69+
python -m pip install recoverpy
7270
sudo recoverpy
7371
```
7472

7573
---
7674

77-
## 💻 Usage
75+
## ▶️ Usage
7876

79-
1. **Launch RecoverPy:**
77+
Start RecoverPy:
8078

8179
```bash
8280
sudo recoverpy
8381
```
8482

85-
2. **Select Partition:**
86-
Choose the partition where your lost data resides. If unsure, try scanning your `/home` partition, it might contain editor or IDE backups.
83+
1. Select a partition.
84+
2. Enter a distinctive search string.
85+
3. Start the scan.
86+
4. Open a result.
87+
5. Inspect and navigate blocks.
88+
6. Save useful content.
8789

88-
3. **Search Content:**
89-
Enter a unique string from the lost file content. RecoverPy will scan disk blocks to locate matches.
90+
Using a unique identifier, configuration key, or sentence fragment generally produces better results than common words.
9091

91-
4. **Find & Recover:**
92-
Results appear interactively. Select a result, preview the block, and save it. Explore neighboring blocks if the file spans multiple disk blocks.
92+
---
93+
94+
## ⚙️ How it works
95+
96+
RecoverPy operates directly on the raw byte stream of a block device.
97+
98+
The selected partition is opened in read-only mode and scanned sequentially using fixed-size chunks. The scanner processes the stream incrementally, keeping a small overlap between chunks to ensure that matches spanning chunk boundaries are not missed.
99+
100+
Pattern matching is performed at the byte level. For every match, RecoverPy records the exact absolute offset within the device. This offset becomes the reference point for block inspection and navigation.
101+
102+
Block reads are performed using explicit offsets rather than relying on filesystem abstractions. This allows precise access to adjacent blocks without loading large portions of the device into memory.
103+
104+
The entire scan is streaming-based and memory-bounded: RecoverPy never loads the full partition into memory.
93105

94106
---
95107

96-
## 💡 Recovery Tips
108+
## ⚠️ Limitations
109+
110+
RecoverPy works on raw data. It does not reconstruct files automatically or infer file boundaries.
111+
112+
Results may be partial or fragmented. If the underlying blocks have already been overwritten, recovery is not possible.
97113

98-
- 🛑 **Unmount partition first:** Reduce risk of data overwriting.
99-
- 🎯 **Be specific:** Use unique, simple search strings.
100-
- ⏳ **Act quickly:** The sooner you scan, the higher your recovery chances.
101-
- 📑 **Check adjacent blocks:** Your file might span several blocks, check them all.
114+
Accessing block devices typically requires sudo. To reduce the risk of further overwriting, avoid writing to the target partition during recovery and unmount it when possible.
102115

103116
---
104117

105118
## 🤝 Contributing
106119

107-
Found a bug or have an idea? PRs, issues, and suggestions are warmly welcome. Check out our [contributing guide](CONTRIBUTING.md) for how to get involved!
120+
If you run into a bug or think something could be improved, feel free to open an issue. And if you’d like to work on it yourself, pull requests are always appreciated.
108121

109122
---
110123

111-
If RecoverPy saved your day, consider ⭐️ starring the repo, thanks for your support!
124+
## 🛠 Development
125+
126+
Project structure:
127+
128+
* `recoverpy/ui/` — Textual interface
129+
* `recoverpy/lib/search/` — streaming search engine
130+
* `recoverpy/lib/storage/` — block and device access
131+
* `recoverpy/lib/text/` — decoding utilities
132+
* `tests/` — unit and integration tests
112133

134+
### Setup
135+
136+
```bash
137+
uv sync --dev
138+
```
139+
140+
### Run locally
141+
142+
```bash
143+
sudo uv run recoverpy
144+
```
145+
146+
### Run tests
147+
148+
```bash
149+
uv run pytest -q
150+
```

0 commit comments

Comments
 (0)