Files and the editor

Opening Files

Files is one of the three things a host can offer, beside Terminal and Screen. Open it from any of these:

• the Files button on the host's page;
• a host tile's Files button;
• on a Mac or an iPad with a keyboard, the Connect menu, Files, or ⌥⌘3;
• a link or a Shortcut (see Shortcuts and links), or Handoff from another device.

If the host has no saved sign in, Conn asks for one before Files opens, and that one answer lasts the whole time Files is open. Files makes its own SSH connection, through the host's jump host if it has one; it doesn't share one with a terminal or a screen.

Files starts in the folder the server gives the account to start in, which on OpenSSH is the account's home folder. While it connects you see Opening files, and a large folder fills in as it arrives, with Reading this folder at the foot until it's all there.

Moving around

• Open a folder with a tap (a click on a Mac). A tap on a file opens it in the editor.
• The path along the top has a button for every folder from / down to where you are. Tap one to go there. Tap the folder you're in to list it again.
• Enclosing Folder, the folder button with an up arrow, goes up one level. On a Mac or an iPad keyboard, ⌘↑ does the same.
• Refresh: iPhoneiPad pull the list down. Mac click the current folder in the path.
• Leave Files with Disconnect in the ⋯ menu. It goes back to the host's page, and any running transfers carry on.

Search, sort and hidden files

• Search this folder filters the folder on screen by name, ignoring case and accents. It doesn't look inside subfolders, and nothing is sent to the server.
• Sort By in the ⋯ menu sorts by Name, Size or Date, smallest and oldest first. Folders always come first. Name is the default.
• Show Hidden Files in the ⋯ menu shows names that start with a dot. It's off each time Files opens. On a Mac or an iPad keyboard, ⇧⌘. switches it.

What a row shows

Each row has an icon for its kind, its name, and underneath, the size (files only) and the date it last changed: a time for today, a day and month for this year, and the year as well for older items.

• Links show an arrow. Conn looks up where each link points (the first 64 in a folder), so a link to a folder opens like a folder.
• A broken link points at something that isn't there. Tapping it does nothing, but you can still rename or delete the link itself.
• Pipes, sockets and devices have their own icons and can't be opened.

Working with files and folders

Touch and hold a row on iPhone or iPad, or right click it on a Mac, for its menu:

Item	What it does
Open / Open in Editor	Opens the folder, or the file in the editor.
Download	Adds the file to Transfers. Files only, not folders.
Copy Path	Copies the item's full path on the machine.
Rename...	Gives it a new name in the same folder.
Permissions...	Changes who may read, write and run it.
Delete	Removes it from the machine, after asking.

The ⋯ menu (top right on iPhone and iPad, at the end of the path on a Mac) has Sort By, Show Hidden Files, New Folder..., Upload a File..., Upload a Photo... (iPhone and iPad), Disconnect and Help.

Rename

Rename sends the new name exactly as you type it. Only a slash, a null character and a name of . or .. are refused; spaces and any other characters are fine, because the machine allows them. To put something in another folder, there's no move yet: see What Files doesn't do yet.

If the new name is already taken, the button reads Replace, and Conn asks first, because replacing deletes the other item. Replacing needs the server to support atomic renames (OpenSSH does); if it doesn't, Conn says so and you can choose another name.

Delete

Delete always asks first. There's no wastebasket on the machine, so Conn can't bring anything back. Deleting a link removes only the link, not what it points at.

A folder has to be empty before it can be deleted. Conn won't empty it for you; it tells you it still has items in it.

New Folder

New Folder... in the ⋯ menu asks for a name. On a Mac or an iPad keyboard, it's ⇧⌘N.

Permissions

Permissions... opens a sheet that shows the permissions Now and After your change, in the rwxr-xr-x form and as an octal number such as 0755.

• Owner, Group and Everyone else each have Read, Write and Run. For a folder, Run reads Enter.
• Special has Set user ID on run, Set group ID on run and Sticky.
• Belongs to shows the owner and group as numbers, because SFTP sends numbers, not names. They can't be changed here.

Apply changes that one item; it doesn't go into a folder's contents. Links have no permissions of their own, so the item isn't offered for them.

Uploading

• Upload a File... opens the system's file picker. You can choose several files at once.
• iPhoneiPad Upload a Photo... opens your photos. Conn doesn't need access to your whole library for this. The uploaded file doesn't keep the photo's original name.

Files go into the folder on screen, with the name they have on your device. An upload never replaces anything: if the name is already there, the upload stops and says so. Transfers opens by itself so you can watch it.

Downloads and Transfers

Download adds a file to Transfers. The Transfers button at the top of Files shows how many are moving and opens the list: a sheet on iPhone and iPad, and a window of its own on a Mac (Window menu, ⌥⌘L).

Each row shows the file, its host, a progress bar, how much has arrived, the speed and the time left. Up to two transfers run at once; the rest wait their turn.

Button	When you see it
Stop	While a transfer is waiting or running.
Resume	A stopped download, or one that failed after part of it arrived. It carries on from where it got to.
Start Again	A download that has to start from the beginning.
Discard	An unfinished download you no longer want.
Share	A finished download: save it to Files, send it in another app, or AirDrop it.
Remove from List	Any finished, stopped or failed row with nothing to discard, finished downloads included.

• Uploads can't be resumed. A stopped or failed upload's part file is removed from the machine (unless the connection went, which can leave a .conn-part to delete), and you upload it again.
• Resume uses the same connection. If the connection has gone, Resume fails straight away; open Files again and download the file again.
• Where downloads go: into Conn's own Downloads folder on the device. Use Share on a finished download to keep a copy somewhere else: on iPhone and iPad, Save to Files; on a Mac, AirDrop, Mail or another app.
• Same name twice: a second download of notes.txt becomes notes (2).txt, and so on. Nothing is overwritten.
• The list starts empty each time Conn opens. Clear History clears it, and asks first if that would delete half-finished downloads.
• Leaving Files doesn't stop a transfer: running transfers carry on, and the connection closes when the last one ends.

Previews

Text files open in the editor. Other files open in a preview when they're one of these kinds: images (PNG, JPEG, GIF, HEIC, WebP, TIFF, BMP), PDF, video and audio (MP4, MOV, M4V, MP3, M4A, WAV, AAC), Pages, Numbers and Keynote files, and Word, Excel and PowerPoint files.

The preview screen says Conn can't edit that kind of file, with a Preview button. Previews have the same 1 MiB limit as the editor. The copy Conn fetches for a preview is kept in its cache and removed when you leave the file's page; any copy older than a day is cleared the next time Conn starts.

The editor

Tap a text file to open it in the editor. Conn reads the file, shows it with line numbers and, for the languages below, syntax colouring.

Extensions	Coloured as
sh bash zsh fish	Shell
py	Python
js mjs cjs / ts	JavaScript / TypeScript
json yml yaml toml	JSON, YAML, TOML
ini conf cfg	INI
xml plist	XML
go rs swift rb pl	Go, Rust, Swift, Ruby, Perl
c h / cpp cc cxx hpp / cs	C, C++, C#

Anything else, such as .md, .log or .txt, opens as plain text. Lines wrap, and the editor follows light and dark mode. On iPhone and iPad the text follows your text size setting.

The key bar

iPhoneiPad Above the keyboard: Hide Keyboard, Undo, Redo, tab (which types the language's indent: a tab for Go, two or four spaces for the others), then the punctuation that language uses most. With a hardware keyboard, the bar sits at the foot of the screen. On a Mac, undo and redo are in the Edit menu as usual.

What the editor opens

• Up to 1 MiB (1,048,576 bytes). A bigger file shows This file is too big for the editor. Download it, or work on it in a terminal.
• UTF-8 text. A file with bytes that aren't text opens Reading only, with stand-in characters, because saving would change it.
• Links open read only: Conn won't save through a link, because that would replace the link with an ordinary file. Open the file the link points at instead.
• A server that can't swap a file into place in one step (it lacks OpenSSH's posix-rename) opens files read only too.

Saving

Save (⌘S on a Mac or an iPad keyboard) lights up when you have changes. While it saves, a spinner takes its place and the text is locked.

Back asks before you lose unsaved changes, and so does anything else that would close the editor: a link, a Shortcut, Handoff, and on a Mac the sidebar and menus.

A save that's refused never throws your typing away. The reason shows above the text, the text stays as you left it, and you choose OK or Read Again.

If the file changed on the machine

Before saving, Conn checks the file's size and time against when it read it. If something else wrote to it in the meantime, Conn won't save over it, so the other change isn't lost. What you typed stays on screen. Read Again loads the newer file in its place, and asks first if that would throw away your typing.

How a save keeps your file safe

1. Conn writes your text to a new file beside the original, named with .conn-part on the end, with the original's permissions.
2. When every byte has arrived, it swaps the new file into the original's place in one step.
3. If anything goes wrong first, the original is untouched and Conn removes the part file.

So a connection that drops mid-save never leaves a half-written file. Two things follow from saving a new file:

• Afterwards the file belongs to the account you signed in as. Its permissions are kept.
• If the connection goes at just the wrong moment, a .conn-part file can be left behind. Conn never deletes it on its own; the next save or upload of that file tells you it's in the way, and you delete it on the machine.

When the connection drops

If the connection ends while Conn is in the background (or while a Mac sleeps), Files connects again by itself when you come back, in the same folder. A file open in the editor keeps what you typed, and Save uses the new connection once Files has reconnected.

If you signed in with a password or key you didn't save, Conn asks for it again: the button reads Sign In and Try Again. If it can't connect, Try Again tries once more.

Sending a file to a screen

On iPad and Mac, you can drop a file onto a Screen session to send it to that machine. It goes over Conn's own SSH connection, into the account's Desktop folder (or the home folder if there's no Desktop), and never replaces a file already there. It needs a saved sign in for the host. See Screen.

What Files doesn't do yet

• Move items between folders, or copy them on the machine.
• Upload or download a whole folder.
• Select several items at once.
• Drag files into or out of the Files list (you can drag onto a screen).
• Make a new empty file. Make one in a terminal with touch, then open it.
• Delete a folder that still has things in it.

Keyboard shortcuts

Keys	Does	Where
⇧⌘N	New Folder...	Mac, iPad
⇧⌘.	Show Hidden Files	Mac, iPad
⌘↑	Enclosing Folder	Mac, iPad
⌘S	Save, in the editor	Mac, iPad
⌥⌘3	Files, in the Connect menu	Mac, iPad
⌥⌘L	Show the Transfers window	Mac

On an iPad with a keyboard, hold ⌘ to see the shortcuts. Every message Files can show, and what to do about it, is in Troubleshooting.