From 34306f071fdcbe899d2cd2f0f9a5bc719c989d63 Mon Sep 17 00:00:00 2001 From: yakamo Date: Fri, 14 Aug 2026 21:05:27 +0100 Subject: [PATCH] Update README.md --- README.md | 84 +++++++++++++++++++------------------------------------ 1 file changed, 29 insertions(+), 55 deletions(-) diff --git a/README.md b/README.md index eeb961a..f7267a8 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ that have already been backed up. This allows the same source folder to be imported repeatedly without creating duplicate copies. -## WHAT IT DOES +### WHAT IT DOES Given a source folder and a destination folder, o-phone.py: @@ -44,7 +44,7 @@ This makes it safe to run the program again later when new photos and videos have been copied from the phone. -## DIRECTORY STRUCTURE +### DIRECTORY STRUCTURE The normal destination structure looks like this: @@ -75,7 +75,7 @@ phone-media-backup/ +-- u-xxx/ -## MEDIA ORGANISATION +### MEDIA ORGANISATION Images and videos are organised by: @@ -93,8 +93,7 @@ The month is written as its full English name rather than a numeric month. -FILENAMES -========= +### FILENAMES Imported files are renamed to: @@ -113,8 +112,7 @@ The SHA-256 hash of the actual file contents is the authoritative duplicate identifier. -SCREENSHOTS -=========== +### SCREENSHOTS PNG files are treated as screenshots. @@ -128,8 +126,7 @@ Other supported image formats remain in the normal date-based directory structure. -UNKNOWN FILE TYPES -================== +### UNKNOWN FILE TYPES Files with formats that are not recognised as normal photo or video media are placed into a directory based on their extension. @@ -151,8 +148,7 @@ would become: u-xyz/ -FILES WITHOUT AN EXTENSION -========================== +### FILES WITHOUT AN EXTENSION Files without a usable extension are handled separately rather than being silently discarded. @@ -160,8 +156,7 @@ than being silently discarded. The exact handling depends on the current version of o-phone.py. -DUPLICATE DETECTION -=================== +### DUPLICATE DETECTION Duplicate detection is based on SHA-256. @@ -189,8 +184,7 @@ This is important because phones can rename files or give different metadata to the same media. -WHY USE A DATABASE? -=================== +### WHY USE A DATABASE? The SQLite database acts as an index of the backup. @@ -221,8 +215,7 @@ SQLite is built into Python, so no external database server is required. -IMPORTANT: DATABASE UPDATE ORDER -================================ +### IMPORTANT: DATABASE UPDATE ORDER The database should only be updated after a successful copy. @@ -241,8 +234,7 @@ This prevents a failed or incomplete copy from being recorded as successfully backed up. -RUNNING THE PROGRAM -=================== +### RUNNING THE PROGRAM The basic command is: @@ -254,8 +246,7 @@ Example: "/Users/yourname/Desktop/phone-backup-moto-g13" \ "/Volumes/all/phone-media-backup" -SOURCE ------- +### SOURCE The first argument is the folder containing the files imported from your phone. @@ -269,8 +260,7 @@ Example: /Users/yourname/Desktop/phone-backup-moto-g13/ -DESTINATION ------------ +### DESTINATION The second argument is the root folder of the backup. @@ -281,8 +271,7 @@ For example: The destination can be located on an external hard drive or SSD. -RECOMMENDED WORKFLOW -==================== +### RECOMMENDED WORKFLOW When new photos are available on the phone: @@ -308,8 +297,7 @@ directories. Therefore it is safe to use the same destination repeatedly. -DRY RUN -======= +### DRY RUN The program supports a dry-run mode when available in the current version. @@ -324,8 +312,7 @@ Example: Always check the output before performing a large import. -DATABASE -======== +### DATABASE The SQLite database is stored inside the destination directory. @@ -342,8 +329,7 @@ Do not delete or manually modify the database unless you understand the consequences. -DATABASE INTEGRITY -================== +### DATABASE INTEGRITY The database is an index of the files in the backup. @@ -364,8 +350,7 @@ The check should be used periodically, especially after manually changing files on the backup drive. -DO NOT MANUALLY ORGANISE THE BACKUP -=================================== +### DO NOT MANUALLY ORGANISE THE BACKUP Once files have been imported, it is recommended not to manually rename or move them. @@ -379,8 +364,7 @@ If files need to be reorganised, future versions of the program may provide dedicated maintenance commands. -SOURCE FILES ARE NOT DELETED -============================ +### SOURCE FILES ARE NOT DELETED o-phone.py is intended to be a backup/import tool. @@ -391,8 +375,7 @@ The source files should remain available until you have independently confirmed that the backup is complete and healthy. -FILE DATES -========== +### FILE DATES The program attempts to determine the most useful date associated with each media file. @@ -414,8 +397,7 @@ When metadata is unavailable, the program uses an appropriate fallback. -RAW FILES -========= +### AW FILES RAW camera files are preserved rather than converted. @@ -424,8 +406,7 @@ They are treated as source files and copied to the backup. The original RAW data is not modified. -SUPPORTED MEDIA -=============== +### SUPPORTED MEDIA The exact list of supported extensions is defined in o-phone.py. @@ -455,8 +436,7 @@ The program may recognise additional formats. Unknown formats are not automatically discarded. -REQUIREMENTS -============ +### REQUIREMENTS macOS or another operating system with Python 3. @@ -468,8 +448,7 @@ separate database server. Some optional functionality may require additional Python packages. -INSTALLATION -============ +### INSTALLATION Check Python: @@ -480,8 +459,7 @@ Run the program directly: python3 o-phone.py SOURCE DESTINATION -SAFETY -====== +### SAFETY Before using o-phone.py with an important archive: @@ -502,8 +480,7 @@ Before using o-phone.py with an important archive: 8. Keep another independent backup of important media. -IMPORTANT PRINCIPLE -=================== +### IMPORTANT PRINCIPLE The SHA-256 hash is the identity of the file. @@ -522,8 +499,7 @@ Conversely, two files with the same filename are not considered duplicates if their contents differ. -PROJECT PHILOSOPHY -================== +### PROJECT PHILOSOPHY The goal of o-phone.py is to provide a simple, dependable and repeatable way to build a personal media archive. @@ -540,8 +516,7 @@ The important principles are: - Prefer simple, inspectable storage over proprietary formats. -EXAMPLE -======= +### EXAMPLE Suppose the phone contains: @@ -579,8 +554,7 @@ If the same source files are imported again, their hashes will already exist in the database and they will be skipped. -BACKUP REMINDER -=============== +### BACKUP REMINDER A single external drive is not a complete backup strategy.