How to Edit a File on an SFTP Server From Your Mac (No Re-Upload)
Short answer: you don't have to download a file from your server, edit it and upload it again by hand. In Folia Files, connect to the server once over SFTP, then double-click the file in the server's folder. It opens in your usual app from a copy on your Mac, and every time you save, Folia Files sends it back to the server, after checking that nobody changed it there in the meantime. You follow the sends in Operations › Remote Files.
This article covers how to set it up, what you see while you edit, and what happens when the server says no.
Why editing a server file is a chore
The classic routine with an SFTP client has three steps: download config.php or index.html, edit it, upload it back. Forget the last step and the server still runs the old version. Do it twice from two Macs and you overwrite someone else's change without noticing.
Mounting the server as a disk looks simpler, since your editor can open the file in place. But apps save badly straight onto a network disk: many write a temporary file and swap it in, leave lock files behind, or wait on every round trip to a slow server. The result can be a file that loses its owner and permissions, or an editor that hangs while it saves.
What you want is the best of both: a local file your editor is happy with, and a server copy that follows every save.
Step 1: connect to the server over SFTP
In the website edition of Folia Files, SFTP connections go through rclone, a free, open-source tool. Install it once in Terminal with brew install rclone (if it's missing, the Connections window offers a button to do it). Then:
- Choose Tools › Connections (Servers and Clouds)… (⌘K) and click New Connection, then pick SFTP / SCP (SSH).
- Enter the server's address, your user name, and a password or your SSH key (leave the password empty to use the key or the SSH agent).
- In Start folder, type the folder you usually work in, for example
/var/www. Folia Files mounts the whole server from its root, so you can still go up anywhere; the start folder is simply the one that opens. - Click Test Connection, then Mount. The server appears in the sidebar's Servers section.
Leave Read-Only off in the connection's options if you want to edit: on a read-only connection, files open as they are, with nothing to send back. If you need more detail on rclone, SSH keys and S3, see how to connect to SFTP and S3 on a Mac without macFUSE.
Step 2: open the file and edit it
Browse the server in a pane like any folder, then:
- double-click the file to open it in its default app, or
- right-click it and choose Open With to pick another app: TextEdit, BBEdit, Visual Studio Code, Nova or any editor you like.
Folia Files downloads a working copy to your Mac and opens it. A banner tells you: "“index.html” opens from a copy on this Mac. Every save is sent back to (your server). Tracked in Operations." If the download takes more than a second, you first see "Opening “index.html”…" with the server's name.
Now edit and save as usual with ⌘S. About a second after your app has finished writing, Folia Files sends the file. It only shows Saved on the server once the server really has the new content: for SFTP, it asks the server directly instead of trusting the mount.
A few details that matter on a web server:
- Permissions stay the same. The file is rewritten in place, so it keeps its owner and permissions on the server instead of getting the defaults of a new file.
- One copy per file. Opening the same file again reopens the same working copy, with any change not yet sent.
- Documents only. Files up to 200 MB go through a copy. Videos, archives, disk images and apps open directly from the server.
This behavior is on by default. The switch is in Settings › Files and Network: "Edit documents on a server from a copy on this Mac, sent back at every save". With it off, files open straight from the server, and you can still right-click a single file and choose Edit and Send Back to the Server.
It isn't limited to SFTP: the same applies to files on your other connections and on any network volume the Mac has mounted, such as an SMB share or a WebDAV server.
Step 3: follow the sends in Operations › Remote Files
Click Operations in the toolbar (the two arrows), or choose Window › Operations in Progress (⌃⌘O). As long as you have files open from a server, the All and In Progress pages show a Remote Files section, one line per file:
- the file's name, and the connection with the file's path on the server;
- its state: Up to Date, Sent at a given time, Sending…, Changes not sent yet, Changed on the server in the meantime, or the error that stopped the last send;
- three buttons: Send Back to the Server, Show the Copy on This Mac, and Finish (deletes the copy on this Mac).
Finish a file when you're done with it. If the server doesn't have your latest version, Folia Files asks first: "Finish without sending the latest changes?". Copies that are up to date and untouched for a week are cleaned up on their own.
When the server says no
The server refuses to write the file
This is the classic case of a configuration file owned by another user, such as php.ini owned by root while you connect as alex. rclone reports a terse "permission denied"; Folia Files turns it into plain words in the banner and in Remote Files:
The server refuses to write this file: the connection's user isn't allowed to change it (the file's owner or permissions on the server).
Your change isn't lost: it stays on your Mac, and the banner has a Try Again button. To fix it, change the file's owner or permissions on the server, or connect with a user who is allowed to write it, then send again. The same goes for "The server has no room left for this file." If the server never confirms it got the file, you see "The server didn't confirm it received the file. The change stays on this Mac."
If the connection drops in the middle of a send, the version the server had before is kept on your Mac, and the banner's Show button takes you to it.
Someone changed the file on the server
Before each send, Folia Files compares the file on the server with the one you opened. If it changed (a colleague, a deploy script, another editor), nothing is overwritten. A banner says "“index.html” changed on the server" and offers:
- Replace the Server's Version: your version goes up; when Folia Files hasn't seen what's on the server, it first keeps a copy of it on your Mac;
- Keep Both: your version is saved next to it as "index (my version).html", and your next saves go to that file.
The server isn't connected
If you save while the connection is down, the banner says the server isn't connected and that the change is kept on this Mac. Click Connect and Send to mount it again and send. The connection's log (right-click the server in the sidebar › Connection Log) lists every file sent and every failure, which helps when something keeps going wrong. If network drives tend to freeze your Mac, this article explains why the Finder freezes on a network drive.
Quitting with changes not on the server
Keep Folia Files open while you edit: it's what sends each save. If you quit while a change hasn't reached the server, it asks:
Some changes to remote files aren't on the server. They stay on this Mac: Folia Files will offer them at next launch (Operations › Remote Files).
Click Cancel to stay and send them, or Quit: at the next launch, the file shows "Changes not sent yet" in Remote Files, and the arrow button sends it. A change left unsent from an earlier session and not saved since, such as a file the server keeps refusing, isn't asked about again at every quit; it waits in Remote Files until you send it or finish it.
Website edition and Mac App Store edition
Everything above describes the website edition, where SFTP works as soon as rclone is installed. Editing through a copy is in both editions, for SMB and WebDAV shares too. In the Mac App Store edition, SFTP connections need Folia Files Companion, a small free app, because Apple's sandbox doesn't let an app start rclone.
More about connections, clouds and editing in place on the servers and clouds page.
