initialize commit

README.md

@@ -1,3 +1,110 @@
 # SFTPsync
 
-PHP utility for synchronize local and remote directories over SFTP.
+Small PHP CLI utility to synchronize directories and manage files on a remote server over SFTP.
+
+## What It Does
+
+- Sync local directory to remote (`--sync`)
+- Sync remote directory to local (`--sync-down`)
+- Delete one remote file (`--delete`)
+- Delete remote directory recursively (`--delete-dir`)
+- Combine multiple actions in one run (executed in CLI order)
+- Skip selected paths during sync or delete using repeatable rules
+
+## Requirements
+
+- PHP 8+ (CLI)
+- PHP `ssh2` extension enabled (`ssh2_connect`, `ssh2_sftp`, ...)
+- Network access from your machine to the target SFTP host
+
+## Quick Start
+
+From repository root:
+
+```bash
+php src/SFTPsync.php --host example.com --user myuser --password mypass --sync ./local /var/www/app
+```
+
+If `--host`, `--user`, or `--password` is missing, the script asks for it interactively (TTY only).
+
+## CLI Usage
+
+```text
+php src/SFTPsync.php --host <host> --user <user> --password <password> [--port <port>] <actions...>
+```
+
+### Actions (repeatable)
+
+- `--sync <local_dir> <remote_dir>`: upload local changes to remote
+- `--sync-down <remote_dir> <local_dir>`: download remote changes to local
+- `--delete <remote_file>`: delete one remote file
+- `--delete-dir <remote_dir>`: delete remote directory recursively (with safety checks)
+
+### Options
+
+- `--host <host>`: required (or prompted)
+- `--user <user>`: required (or prompted)
+- `--password <password>`: required (or prompted)
+- `--port <port>`: optional, default `22`
+- `--print-relative`: show paths relative to action root in logs
+- `--skip <file_or_dir>`: repeatable, applied to `--sync` and `--sync-down`
+- `--skip-delete <file_or_dir>`: repeatable, applied to `--delete` and `--delete-dir`
+- `-h`, `--help`: show help
+
+## Examples
+
+```bash
+# Upload local -> remote
+php src/SFTPsync.php --host example.com --user u --password p --sync ./app /srv/app
+
+# Download remote -> local
+php src/SFTPsync.php --host example.com --user u --password p --sync-down /srv/backups ./backups
+
+# Multiple actions in one run (executed left-to-right)
+php src/SFTPsync.php --host example.com --user u --password p \
+  --sync ./a /remote/a \
+  --delete /remote/a/old.zip \
+  --sync-down /remote/logs ./logs
+
+# Skip selected entries during sync
+php src/SFTPsync.php --host example.com --user u --password p \
+  --skip .git --skip node_modules --skip cache/tmp \
+  --sync ./app /srv/app
+
+# Delete remote directory but keep selected subpaths
+php src/SFTPsync.php --host example.com --user u --password p \
+  --skip-delete .well-known --skip-delete uploads/keep \
+  --delete-dir /srv/app
+```
+
+## Sync Behavior
+
+For each file pair, transfer happens when:
+
+- target file does not exist, or
+- file size differs, or
+- source mtime is newer than target mtime
+
+After upload/download, mtime is propagated to the target when possible.
+
+## Skip Rule Matching
+
+- Rule without slash (example: `node_modules`) matches any path segment with that name.
+- Rule with slash (example: `cache/tmp`) matches that subpath within a relative path.
+- Rules are normalized to forward slashes.
+
+## Safety Notes
+
+- `--delete-dir` refuses dangerous roots such as empty path, `/`, `.`, `..`, and similar dot paths.
+- Delete operations run only on the remote side.
+- Path handling normalizes slashes and trims duplicate separators.
+
+## Exit Codes
+
+- `0` success
+- `1` runtime/SFTP error
+- `2` invalid CLI arguments
+
+## Output
+
+The script prints status lines (`MKDIR`, `UPLOAD`, `DOWNLOAD`, `DELETE`, `RMDIR`, `SKIP`, `ERROR`) and a final summary with operation counters.