How a file is written
The editor writes a file back the way it read it — the same encoding, a byte-order mark only if it had one, each line with its own ending — unless you choose otherwise. This page is that, the header that says it, and files that change underneath or cannot be written.
At a glance
| Key | Action |
|---|---|
| ⇧F4 | How it is written… |
| ⌘E | Encoding… |
| ⇧F9 | Spaces and tabs |
| F2 | Save |
| ⇧F2 | Save as… |
The header line
The name is on the left, with • after it while there are changes not saved, and the line is orange.
On the right, whichever of these apply:
- changed on disk — ⌘R to re-read, changed on disk (now shorter) — ⌘R to re-read, moved or deleted on disk
- The file has changed since it was read, and you have changes not saved — see files that change.
- re-read from disk
- The file changed and was read again.
- not found, 12 replaced, not saved — …
- What just happened, or why something could not. It stays until the next change.
- saving…
- The file is being written.
- read-only
- It cannot be written back.
- UTF-8 (detected)
- The encoding it will be written in, and how that was decided: (BOM) the file says so at its start, (detected) worked out from its bytes, (chosen) chosen by you.
- LF, CRLF, CR, mixed
- How its lines end. LF → CRLF: they will be written another way.
- column
- A column block is marked.
- Go
- The language it is colored as.
- 18:31 of 41
- The cursor’s line and column, and how many lines there are.
Over a format’s own view, what the view has to say takes the place of the last three. When the window
is too narrow for all of it, the encoding goes first, then the line endings, the language, the indent,
column and the cursor’s place. Only then is the name shortened; the • and what happened to the
file stay.
Encodings
A file is read the way the viewer reads it: as its byte-order mark says; as UTF-16 if its zero bytes fall every other byte; as UTF-8 if every byte is valid UTF-8; and otherwise as Latin-1, which reads anything. Saving writes it back the same way.
- The editor never reads a file again another way. To see how it reads as something else, open it in the viewer with ⇧F3 and use ⌘E there.
- Here, ⌘E changes the encoding the file will be written in, in turn: UTF-8, UTF-16 LE, UTF-16 BE, Latin-1. The text stays as it is; only its bytes will differ. A byte-order mark is kept if the file had one, and never added.
- A character the encoding cannot hold is asked about when you save: Characters would be lost. Write writes it anyway, with those characters replaced; Cancel leaves the file unwritten.
Choosing how it is written
⇧F4 sets everything the bytes depend on at once, without changing a character:
- Encoding
- UTF-8, UTF-16 LE, UTF-16 BE or Latin-1.
- Start with a byte-order mark
- A mark at the start of the file saying which encoding it is. Gray for Latin-1, which has none.
- Line endings
- As they are — each line keeps its own, and what they are now is in brackets — or every line LF, CRLF or CR.
Use applies all three.
- It is not a step of undo: choosing again is how to take it back. As they are gives a file whose lines end several ways back exactly as it was.
- It says which ending, never whether: a last line with no line break still has none.
- It counts as a change: the
•shows, and closing asks. - It is for the text. Over a format’s own view, switch to the text first.
Each line keeps the ending it was read with, and a line you start takes the one the file mostly uses. ⇧F9 draws them at the ends of the lines — see Show spaces and line endings.
What a save does
- The file is written beside itself under another name, then put in its place, so a save that fails leaves the original as it was. The header says not saved — and why.
- The file keeps its permissions, access list, owner, group and attributes: a script stays executable.
- A file that has another hard link, or an owner or group you may not give a file to, is written where it is instead, so that it keeps them. A save of one that fails part-way can leave it cut short.
- Saving through a link replaces the file the link points to, and the link stays a link.
- Before it writes, the editor checks that the file has not changed since it was read — see below.
- Every save is in the journal.
A file that no longer parses
Saving JSON, YAML, XML or a property list whose text does not parse asks first: This does not read as JSON, with the line and column where it stops and what is wrong there.
- Go to the error
- Puts the cursor at that place and writes nothing.
Enterdoes this. - Save anyway
- Writes the file as it is.
- Cancel
- Writes nothing and leaves the cursor where it was.
- The file’s extension says what it is, and for ⇧F2 the name you type does. A
.txtfile is never asked about, whatever is in it. - It is asked on every save while the mistake is there, including for a file that was already broken when you opened it.
- Comments and a trailing comma in JSON, a YAML file of several documents and an XML file with more than one element at the top are not mistakes here. Neither is an empty file.
- A file over 20 MB is not checked, and neither is a binary or old-style property list.
- TOML is not checked.
- Closing with changes and choosing Save asks the same question. Any answer but Save anyway leaves the editor open.
Files that change
| Key | Action |
|---|---|
| ⌘R | Re-read |
The editor looks at the file once a second. When something else writes to it and you have no changes waiting to be saved, it reads the file again by itself, keeps the cursor where it was, and the header says re-read from disk. ⌘Z brings back what was there before — the way back when another program wrote something wrong.
With changes not saved, nothing you have typed is touched: the header says changed on disk — ⌘R to re-read, and when the file has been moved or deleted, moved or deleted on disk. ⌘R asks first — Re-read from disk:
- Discard my changes reads the file. ⌘Z brings your changes back.
- Compare opens the comparison of the file on disk, on the left, with your text, on the right. Take changes across either way; what you take into your text and save there is in the editor when you close the comparison, still to be saved, and saving it then replaces the file without asking again.
- Cancel leaves both alone.
Saving over a file that changed asks the same — The file has changed, with Overwrite in place of Discard my changes. For a file that is gone, Write puts it back where it was. Nothing is merged for you.
Files that cannot be edited
- A file over 64 MB
- Is not opened, and says how big it is. ⇧F3 reads a file of any size.
- A file that is not text
- One whose first 64 KB hold a zero byte, or are more than a third control characters. It opens, with not text — editing it would rewrite what is not in the header, and the first change asks: This does not look like text. Edit anyway lets you; ⇧F3 shows it as bytes instead.
- Bytes this reading cannot reproduce
- A file that reads as UTF-8 at its start but is not UTF-8 further in, for one. Written back, it would not be the same bytes, so it opens read-only and says not written back — bytes this reading cannot reproduce. The viewer reads it, with ⌘E for the encoding it is really in.
- A file you are not allowed to read
- Says why, in place of the text.
- A folder, or an application
- Nothing opens.
Something with no file of its own
An item on the Clipboard, or anything else listed without a file behind it, opens in the editor the same way. F2 sends it back where it came from — asking first, where that place has something to ask — and ⇧F2 writes it to a file, which the editor then is. Where it was marked as sensitive, Save as says Marked as sensitive: this writes it to disk. If it changes where it came from while it is open, the header says so.