Initial commit

README.md

@@ -0,0 +1,74 @@
+# teledrive_restore
+
+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
+```