Before the first deploy

Somebody moves a blog off WordPress onto blog.sh and keeps the same hosting, the same directory, the same address. The build is ready, the first deploy goes through without an error — and the front page is still the old one. Nothing went wrong in the upload. The old site was simply never taken away, and the host prefers it.

A deploy only removes what it wrote

A deploy writes the site's files, and deletes only files an earlier deploy of the same site put there. Everything else in the target stays, on purpose: the engine has no way of knowing whether a file it did not write is a leftover or something you need, and a deploy that guessed wrong once would be a deploy nobody trusts again.

That rule is right, and it has one sharp consequence. Most shared hosting serves index.php before index.html, so an old WordPress front page goes on answering at the root while the new index.html sits right beside it, unseen. An old .htaccess can keep rewriting addresses the new site depends on. The upload succeeded; the reader just never reaches it. (The git backend is the exception — every push replaces the whole branch, so nothing old survives there.)

Ask the target first

doctor --online reads the root of the deploy target and names everything in it the site does not put there:

$ ./blog.sh doctor --online
⚠️  The deploy target (/var/www/myblog) holds 5 item(s) in its root that this site does not put there: .htaccess, google1234abcd.html, index.php, wp-content/, wp-login.php.
   One of them is index.php, which a host serves before index.html -- an old front page can go on hiding the new one. A deploy never deletes what it did not write, so these stay and are served beside the site. Delete what you do not want by hand (FTP, the host's file manager); and name what is there on purpose under deploy.keep in config/site.yml, and doctor stops listing it (.well-known, where a host keeps its certificate challenge, is never listed).

It works the same way on every backend — Surfer through its API, a local directory by reading it, rsync, rclone and sftp by listing the directory — with one request and a deadline, so a host that does not answer is a warning rather than a hang. Run it once the target is set in env.sh and before anything is uploaded.

Clear it, and keep what is meant to stay

The clearing is yours to do, with whatever you used for the old site: an FTP client, the host's file manager. Leave what the host itself put there. .well-known/, where a host keeps its certificate challenge, is never listed in the first place.

Some things are there on purpose — a verification file a search console asked for, screenshots an old issue still links to. Name those under deploy.keep in config/site.yml:

deploy:
  keep:
    - google1234abcd.html

and the next run is quiet about them:

✅ The deploy target (/var/www/myblog) answers, and everything in its root is this site's.

Only doctor reads that list. A deploy never deletes what it did not write either way, so keep is a note to doctor, not a lock on the target.

The program behind the backend

Four of the six backends hand the upload to a program — rsync, rclone, sftp, git — and a machine without it used to find out from the first deploy, after the whole build had run. doctor asks now:

❌ The rsync backend runs rsync, and rsync is not installed here -- every deploy would fail after the build.
   Install rsync from your system's packages, then run ./blog.sh doctor again.

rclone has one trap of its own. Installed as a snap, it can read only inside your home directory, so a site kept in /srv fails every deploy on files that are plainly there. doctor names that too, and points at the distribution's package or rclone.org instead.

And do not point it too early

One more thing worth knowing before the target goes into env.sh: saving a draft builds and deploys the site, because a draft's preview is a real address on the real site. The first deploy is rarely the one you type by hand. An unedited env.sh deploys nowhere and everything else works — writing, previewing, importing — so the target can wait until the site is ready to be seen, and until doctor --online has had its look at what is already there.