teledrive-recovery/README.md

# teledrive_restore

> [!WARNING]
> **Use at your own risk.** This script has not been thoroughly tested. Always make sure you have a backup of your files before running it, especially with the `mv` (move) operation. The author takes no responsibility for any data loss or damage caused by the use of this script.

A command-line utility to restore files from a flat TeleDrive export dump back into their original folder hierarchy, using the metadata exported from TeleDrive as a `files.json` file.

## Requirements

- Python 3.6 or newer (no third-party packages required)

## Background

TeleDrive stores all uploaded files in Telegram as flat message attachments. When you export your data, you get:

1. A `files.json` metadata file describing every file and folder, including parent-child relationships.
2. A flat directory of downloaded files, all sitting in the same folder.

This script reads the metadata and reconstructs the full directory tree, placing every file in its correct folder.

## Usage

```
python3 teledrive_restore.py <operation> <files_json> <source_dir> <dest_dir>
```

### Arguments

| Argument | Description |
|---|---|
| `operation` | `mv` to **move** files, or `cp` to **copy** files |
| `files_json` | Full path to the TeleDrive JSON export (any filename is accepted) |
| `source_dir` | Path to the flat directory containing all your downloaded TeleDrive files |
| `dest_dir` | Path to the root destination directory where the folder tree will be created |

### Help

```
python3 teledrive_restore.py --help
```

## Examples

**Copy** all files into a restored tree (original flat dump is kept intact):

```bash
python3 teledrive_restore.py cp /home/user/files.json /mnt/teledrive_dump /mnt/restored
```

**Move** all files into a restored tree:

```bash
python3 teledrive_restore.py mv /home/user/files.json /mnt/teledrive_dump /mnt/restored
```

## Behaviour

- The destination directory is created automatically if it does not exist.
- Nested folders of arbitrary depth are supported.
- Files at the root level (no parent folder) are placed directly in `dest_dir`.
- If a file **cannot be found** in `source_dir`, a `WARNING` is printed and the script continues with the next file.
- If a file **already exists** at the destination, a `WARNING` is printed and the file is skipped.
- A summary of moved/copied, missing, and skipped files is printed at the end.

## Output example

```
Loaded 6800 entries from /home/user/files.json
Files to process: 5440
WARNING: File not found in source, skipping: some_missing_file.pdf
...

--- Summary ---
Copied: 5438
Missing (not found in source): 1
Skipped (already at destination): 1
```

## License

Copyright (C) 2026 Anders da Silva Rytter Hansen, PC-Rytteren ApS

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

See the [LICENSE](LICENSE) file for the full license text.