The `sync app` is a lightweight but powerful command-line utility designed to keep files and directories in perfect harmony across multiple locations—whether you’re mirroring a project folder to an external drive, syncing config files between two machines, or maintaining a backup of a critical directory. Unlike cloud-based sync tools, `sync app` works entirely locally, giving you full control over bandwidth, conflict resolution, and scheduling. This guide walks you through installation, core usage, advanced techniques, and the pitfalls to avoid.

`sync app` is available for Windows, macOS, and Linux. On most systems, you can install it via a package manager:

After installation, verify the setup by running:

```bash sync version ```

You should see the version number. The first time you run any sync command, the app will create a hidden configuration directory (`.sync-app/`) in your home folder. This stores logs, lock files, and your sync profiles.

The most common operation is a one-way mirror, where the source overwrites the destination. To sync `~/Documents/Projects` to an external drive mounted at `/Volumes/Backup/Projects`, use:

```bash sync app source ~/Documents/Projects destination /Volumes/Backup/Projects mode mirror ```

Example: ```bash sync app source ~/Code destination ~/Dropbox/Code mode bidirectional ignore ".git" ignore "node_modules" ```

The `ignore` flag accepts glob patterns. Always ignore version-control folders and dependency directories to avoid massive, unnecessary file transfers.

Before executing a real sync, always perform a dry run to see what would happen:

```bash sync app source ./src destination ./dst mode mirror dry-run ```

The output lists every file to be copied, updated, or deleted. Review it carefully—this is your safety net.

For logging, use `log-level verbose` to see detailed per-file actions, or `log-file sync.log` to write everything to a file. I recommend always logging to a file for audit trails, especially when syncing large trees.

Conflict handling: In bidirectional mode, if a file is modified on both sides since the last sync, `sync app` will by default keep both versions, renaming the older one with a timestamp suffix (e.g., `report_final (2025-03-14 10:22).pdf`). You can change this to `conflict-strategy overwrite-newer` (keeps the most recently modified file) or `conflict-strategy abort` (stops the sync until you manually resolve). For safety, stick with the default `keep-both` unless you are absolutely certain about your workflow.

`sync app` doesn’t run in the background by design. To automate it, use your operating system’s scheduler.

On macOS/Linux (cron): Open your crontab with `crontab -e` and add a line to run the sync every hour:

``` 0/usr/local/bin/sync app source ~/Documents destination /Volumes/Backup mode mirror log-file ~/sync.log ```

On Windows (Task Scheduler): Create a new task, set the trigger to “Daily” or “On an event,” and set the action to run the full path of `sync-app.exe` with your arguments.

Pro tip: Add `lock-timeout 30` to prevent overlapping runs. If a previous sync is still running (e.g., due to a large file), the new instance will wait up to 30 seconds, then exit with an error. This avoids corrupted states.

Beyond `ignore`, you can use `include` to sync only specific file types:

```bash sync app source ./docs destination ./backup mode mirror include ".pdf" include ".docx" ```

Note: `include` overrides `ignore` for matching files. Order matters—the app processes rules in the order you list them. So if you want to exclude everything except PDFs, you must first ignore all, then include PDFs:

```bash sync app source ./docs destination ./backup mode mirror ignore "" include ".pdf" ```

By default, `sync app` uses file size and modification time to decide if a file changed. This is fast but can miss changes if timestamps are altered. For critical data, use `checksum` to compare file hashes (SHA-256). This is slower but guarantees accuracy. Use it for configuration files or encrypted archives.

Add `preserve-permissions` to copy Unix file modes and ownership (requires root on some systems). Use `follow-symlinks` if you want to sync the target of a symlink rather than the link itself. By default, symlinks are copied as links, which is usually what you want.

Imagine you maintain a static website. Your local `assets/` folder is the source of truth. You want to deploy to a server via an SSH-mounted directory.

```bash sync app source ./assets destination /mnt/server/html/assets mode mirror ignore ".tmp" ignore ".bak" checksum log-file deploy.log ```

Because you used `checksum`, any file whose content changed—even if the timestamp didn’t—will be updated. This is essential when using CI/CD tools that rewrite files with identical timestamps.

1. Syncing to a folder inside the source – This creates an infinite loop. Always ensure the destination is outside the source directory tree. `sync app` will detect this and refuse to run, but double-check your paths.

2. Case-insensitive filesystems – If you sync from a Linux (case-sensitive) system to a Windows or macOS (case-insensitive) system, files named `Readme.txt` and `readme.txt` will collide. The app will rename one to `readme (1).txt`. To avoid surprises, standardize your filenames to lowercase.

3. Network drives disconnecting mid-sync – When syncing to a mounted network drive, always use `resume` (if available) or set `retry 3` to retry failed transfers. Additionally, add `timeout 60` to prevent hanging on unresponsive connections.

4. Running as root – On Unix systems, avoid running `sync app` as root unless absolutely necessary. Permission errors on files owned by other users can cause partial syncs. If you must, use `no-permission-check` to suppress warnings, but understand the risks.

5. Forgetting the dry run – The single most common mistake. Even after months of use, I still do a `dry-run` before every critical sync. It takes two seconds and saves hours of headache.

`sync app` is a robust tool, but its power comes from careful usage. Start simple, use dry runs religiously, and gradually adopt advanced flags as you become comfortable. With practice, you’ll wonder how you ever managed files without it.