← All posts

Sync a local folder with a server on Mac, with a preview first

To sync a local folder with a server from your Mac in both directions, a tool has to compare the two trees, decide which side each difference should flow to, and then copy. The comparing is easy. The deciding is where syncs go wrong, so the safest kind of two-way sync works out the full plan first, shows it to you, and only runs once you agree. This post explains what that plan has to get right, so you can judge any sync tool, and shows how the review step works in practice.

One-way and two-way sync are different jobs

A one-way sync makes the destination look like the source. Deploying a website is one-way: your build is the truth, and the server should match it. The usual command-line tool for this is rsync, and its --dry-run flag with -i (itemise changes) is a good way to preview:

rsync -avi --dry-run ~/Projects/site/dist/ deploy@example.com:/var/www/site/

A two-way sync treats both sides as places where work happens. You edit files on your Mac, a colleague or a process changes files on the server, and the goal is for both to end up with everything. That is harder, because the tool must work out which side changed, not just that the two differ.

Spotting what changed

There are two ways to tell whether two copies of a file are the same:

Comparing times has a catch: precision. SFTP version 3, the version most servers speak, reports modification times in whole seconds, while APFS on your Mac records fractions of a second. FAT-formatted drives round to two seconds. A tool that demands exact equality will think almost every file differs, so sensible tools allow a small tolerance.

Times also need preserving. If uploading a file gives the server copy the time of the upload instead of the original's, the next comparison sees the server copy as newer, and the file bounces back and forth forever.

Conflicts: when both copies differ

When a file exists on both sides with different contents, the obvious rule is "newest wins". It is usually right, and a good default. But it is a guess. Without a record of each file's history, a tool cannot tell "changed here only" from "changed on both sides", and when the two times are within the tolerance there is no newer copy at all. A trustworthy sync shows you these cases, with both sides' sizes and dates, and lets you override the default per file.

Deletions: the dangerous part

Suppose notes.md is on the server but not on your Mac. There are two possible stories. Either it is new on the server and should be copied down, or you deleted it locally and it should be deleted on the server too. The two folders look identical in both cases.

The only way to tell them apart is memory: a record of what existed on both sides after the last sync. If the file was there last time and is now gone from one side, it was deleted. If it was never seen before, it is new. A tool without that record that still propagates deletions is guessing, and when it guesses wrong, it deletes your files. That is why the safe default is to copy missing files rather than delete them, and to treat deletion as something you switch on deliberately. Why folder sync should not delete by default goes into this in more depth.

Previewing the plan before it runs

Put together, a sync plan is five lists: files to upload, files to download, conflicts with a proposed resolution, deletions (if enabled), and folders to create. Seeing those lists before anything moves is what turns sync from an act of faith into a routine check. Thirty seconds reading the plan catches the wrong folder, the forgotten node_modules, and the conflict you did not expect.

How to sync a local folder with a server on Mac in Wharf

Wharf's Sync button compares the folder in the local pane with the folder in the remote pane, over SFTP, FTP or FTPS. It scans both trees, showing the number of folders scanned while it works, and you can click again to cancel. Then it opens a Review Sync sheet before anything is copied.

The sheet shows both paths and a summary line (how many files to upload, to download, in conflict, and already matching), then the lists themselves:

Resolve All sets every conflict at once: Keep Newer, Use Local Everywhere, Use Remote Everywhere or Skip All Conflicts. The footer shows how much data will be transferred. Nothing happens until you click Start Sync, and the work then appears in the Transfers list like any other transfer.

Under the hood, Wharf compares size and modification time with two seconds' tolerance and does not hash contents. It sets the server copy's time to match after each SFTP upload, so unchanged files stay unchanged next time. .DS_Store, .localized and Thumbs.db are ignored, and symlinks are skipped rather than followed.

Deletions stay off unless you tick the box

By default, a file missing on one side is copied back from the other. Ticking Also delete files removed on the other side in the review sheet re-plans with deletions included, so you see exactly which files would go before confirming. Wharf detects deletions against the previous sync pass, so the first pass can never delete anything, and the record is not kept between launches. Local files are moved to the Trash; files on the server are removed permanently. The checkbox appears in every review sheet, so you always see whether deletion is on before you confirm.

Keeping a pair in step

The Keep in Sync toggle starts continuous sync, and its first pass goes through the same review sheet. After that, local changes are picked up within about a second and the server is checked every 15 seconds by default, adjustable in Settings. Continuous sync applies only the clear-cut cases on its own. Conflicts it cannot decide are left alone and listed for you to review, rather than overwritten on a coin toss.

The sync section of the homepage summarises the approach, the support page covers why a sync did not delete anything, and deploying a static website over SFTP shows the same tools used for a one-way deploy.