The delete that did not delete

I publish this site from a folder of notes. I write in Markdown, press a button in a small panel I built, and each note is written out as a page and put online. Nothing about it is clever, which is why it has worked for years.

Then I decided to remove four old projects. They were finished, or abandoned, and they did not belong in the list anymore. Before I deleted them, I read my own tool. I am glad I did. It could add pages. It could update pages. It could not remove them.

What the tool actually did

Every time I pressed the button, it walked the folder and wrote each note out to the site. A new note appeared. A changed note was rewritten. A note that had not changed was left alone.

Notice what is missing from that sentence. Nowhere does the tool compare the folder against the site and ask what the site has that the folder does not.

So removing a note from the folder changes nothing at all. The page stays. The address keeps answering. Search engines keep being told it exists. And nothing tells me, because from the tool's point of view nothing has gone wrong. It did its job. It wrote the files that existed.

Two sides, and I had only built one direction.

Why that happens

The two directions look similar and are not.

Adding is easy and visible. You press a button, files appear, you see them. Removing needs something else: a list of what is on each side, a comparison, and then the nerve to delete something a machine has decided is unnecessary. If the comparison is wrong, the tool deletes the wrong thing, and that is a much worse day than a missing page.

I did not skip it on purpose. I wrote the tool while the site was growing, when everything only ever went one way. A publisher adds pages. The other direction never came up.

The fix, and the two things it refuses to do

The fix is to look for leftovers on purpose. Before deleting anything, the tool now lists every file on the site that has no matching note in the folder, and it shows me that list.

Two things it refuses to do, both because deletion is the part that cannot be undone.

The first: it will not act when the folder side comes back empty. If the folder is missing, or a cloud drive has not finished downloading, an honest comparison says that everything on the site is a leftover. That is the one mistake that would take the whole site down, so an empty folder is treated as a reason to stop.

The second: it only touches files whose names it created itself. Anything I put there by hand is invisible to the check, and safe from it, permanently.

And it does nothing at all unless I tick a box. The list is free. The deletion is my decision.

The half I missed

I fixed the words, felt good about it, and then, while publishing a post with a picture, I checked the other half of the same tool.

The pictures had the same bug, and nobody had ever looked.

• Images were copied to the site in the same one-way fashion. Adding worked. Removing did not exist.
• So when a post was deleted, its picture stayed in the folder. Forever.
• The page was gone. Nothing linked to the picture. And unlike a page nobody links to, which at least has an address and can turn up in search, a picture nothing points at appears in no list anywhere, ever. It just sits there, taking up space, invisible.

Between the two, the picture is the one I would never have found by using the site. A leftover page can be stumbled on. A leftover picture needs a tool built to look for it.

The same fix went in, with the same two guards. Then I tested it properly for the first time: I planted three fake leftovers next to a real picture, ran the check, watched it name all three and delete them, and confirmed that the real one was still there.

The rule

A copy is not a mirror. If a tool can add something, ask what it does when something is removed. That question is usually the difference between a tool that maintains a thing and a tool that slowly fills up with the past.

And test the removal path on purpose, before the day you need it. I found this by reading my own code before deleting four projects. If I had not, I would have learned it from a search result for a page I thought was gone.