Chapter 8

Versions

Every save keeps a version of the whole book. Look back at any of them, see what has changed since, put back one scene or everything, and find a passage you cut months ago.

Every save is a version

When you choose File → Save ⌘S, Septangular writes every scene, entry and note you’ve changed, and any change to the book’s structure, and then keeps a copy of the whole book folder as it stands: one version. There’s nothing to set up. A save that changes nothing makes no version.

Some versions are made for you:

Auto-save

Septangular also saves on its own, a few minutes after you make a change: by default, five. To change how long it waits, or to turn it off, use the Auto-save menu in the Versions sidebar:

The time is counted from the first change since the last save, not the latest, so steady typing is still saved on time. With nothing unsaved, auto-save does nothing. The setting belongs to the book: each book keeps its own, and restoring an earlier version doesn’t change it.

Writing sessions

Septangular marks the end of a writing session for you, at the latest version, when:

• you close the book’s window, or quit;
• you open another book in the same window (moving between books of one series doesn’t end a session, since they share one history);
• thirty minutes pass without typing. Septangular saves first, so the session’s work is in the version it marks.

Each version is marked once at most, so closing the book again without writing adds nothing.

The Versions list

The Versions sidebar lists the history newest first, grouped by day under “Today”, “Yesterday” or the date, each version with its time. To keep the list short, it shows:

• the latest version, marked “Latest:”;
• every snapshot and published edition, in bold with a bookmark;
• every “Session ended”.

Tick Show every save to list every version, each named by what made it, such as “Saved” or “Auto-saved”. Hover over any version to see that name.

A version’s page

Click a version to see its page. At the top are its name, when it was saved, and its Fingerprint: a long string of letters and digits worked out from the version’s contents and from every version before it. If anything in an earlier version were altered, every fingerprint after it would change. The writing record prints fingerprints, so that a record can be checked against the book.

Below, under Changed since then, is every file that differs between that version and the latest one, by its place in the book’s folder, such as manuscript/03-the-lamp-room.md:

The latest version’s page has no list: it is the book as last saved.

Compare

Compare sets the file as it was in that version on the left beside the latest version on the right, with the changes marked and long unchanged stretches folded away; click a fold to open it. You see the scene’s text as it’s written in its file, with its Markdown marks (see Appendix B). Click the arrow at the top left to go back to the version.

Compare in the Versions list shows the book as last saved. To compare a scene with unsaved edits included, use its own history (see A scene’s history).

Restore

A restore never loses work. Before it changes anything, Septangular saves what you have, unsaved edits included, as a version. After it, the restored book is saved as a version too, named “Restored …”. To undo a restore, restore the version from before it.

• Restore, beside a file, puts that one file back as it was in the version, and leaves the rest of the book alone.
• Remove, beside a file added since, deletes the file, as it wasn’t part of that version. Its text stays in the history, and you can bring it back from the version before the removal.
• Restore Everything to This Version makes the whole book folder as it was: every scene, the book’s structure and title page, its targets, the outline, Story Bible and notes. Files added since are deleted, and files deleted since come back.

A scene’s place in the book is kept in book.xml, not in the scene’s own file. So restoring the file of a scene deleted since puts its text back in the book’s folder, but not in the book. To bring a deleted scene back into the book, use Bring Back to the Stash in Find in History instead.

Septangular asks before each restore. Afterwards the book reloads, and any scene you have open shows its restored text.

In a series, the books share one history, so Restore Everything to This Version puts back every book in the series and the shared Story Bible. See Chapter 10.

Snapshots

A snapshot gives a version a name you can find again, such as “First full draft” or “Sent to my editor”. To take one:

1. Click Take Snapshot… at the top of the Versions sidebar.
2. Type its name under “Name this snapshot:”.
3. Press ↩ or click Take Snapshot. Esc or Cancel puts the box away.

Septangular saves first, so the snapshot holds everything you’ve written, and then names the latest version. A snapshot needs a name. It shows in the list in bold with a bookmark, however the list is set, and its version’s page takes its name. Two snapshots of the same version are listed together, separated by a dot. Snapshots can’t be renamed or removed.

Snapshots show elsewhere too: in a scene’s history, beside the versions of the scene they hold, and in the Manuscript’s revision heat, which can count the revisions since any snapshot (see Chapter 3).

Published editions

When you mark a build as published in Publishing, Septangular records the version it was built from (see Chapter 9). Those versions show in the list like snapshots, as “Published: ” and the edition’s name, such as “Published: Paperback”, and in the writing record’s milestones.

A scene’s history

To see how one scene got where it is, right-click it in the Manuscript sidebar and choose History…, or choose Manuscript → Scene History… for the scene you’re in. Its history takes the editor’s place, listing only the saved versions where that scene changed, newest first. Each entry gives:

• when it was saved, with “Latest saved” on the newest and the name of any snapshot that holds that text;
• the scene’s words then, and the change: “855 → 871 words (+16)”. The first entry says “Started”, and an entry where the scene left the book says it was “Taken out of the project”;
• how many paragraphs were new or rewritten, and how many taken out, or “spacing only”;
• the first few words of the first new or rewritten paragraph.

Compare with Now sets that version beside the scene as it is in the editor, unsaved edits included. If the scene has unsaved edits, the history says so: they aren’t in its history yet. Restore This Version, or Restore Left while comparing, puts back just this scene, saving your work first as every restore does.

Click the arrow beside “Back to the scene”, or choose any scene in the sidebar, to go back to writing.

Find in History

Find in History searches every saved version of every scene, note and Story Bible entry for a passage, including ones you cut long ago. To open it, click Find in History… in the Versions sidebar, or choose Edit → Find → Find in History… ⌥⌘F from anywhere. When Find ⌘F finds nothing in the book, it offers Look for it in the history…, which carries your words and options over.

Type at least three characters of the passage. Septangular searches as you type, or when you press ↩, and lists each paragraph that ever held the words. The words are found in order, whatever the spacing between them and across line breaks. Curly and straight quotation marks are the same to it, and so are italic and bold marks between words.

Each passage says where it was and what became of it:

• “Cut from” the scene, and when;
• “removed with its file”, when the whole scene, note or entry went;
• “but it’s elsewhere in the project now”, when it was cut from one file and is in another, as when a paragraph moves to another scene. Such a passage counts as still there;
• “Still in” the scene, for text that hasn’t gone.

Each wording of a paragraph is a passage of its own, so a paragraph you rewrote shows its earlier wording as cut. The most recent 200 passages are listed.

Copy copies a passage just as it was written, Markdown marks and all. Show the Version of … opens Versions on the last version that held the passage, comparing its file then with the latest version. To come back to the search, click Find in History… again: it opens where you left it. Back to Versions leaves it.

Files no longer in the project

Below the passages, Files no longer in the project lists every scene, note and Story Bible entry that was saved in some version and isn’t in the book now, however long ago it went, with its words and when it was removed. Before you search, it lists them all; with words in the box, only those whose name has the words, or that had the passage when they were removed.

• Bring Back to the Stash, for a scene, puts it back in its folder and adds it to the Stash, from where you can move it into the book. The scene’s file is saved as a version at once, but its place in the Stash is unsaved until you save.
• Bring Back, for a note or Story Bible entry, puts it back where it was, and saves that as a version.
• Show the Version of … shows the file in the last version that had it.

A file comes back under its old name, or with “-recovered” added if that name has been taken since. Your work is saved before anything comes back.

The writing record

The writing record is a PDF account of how the book grew, drawn from its history: a way to show an agent, a publisher or a prize how the book was made, a day at a time.

To make one, click Writing Record… in the Versions sidebar. Septangular saves first, then asks where to put the PDF, suggesting “Title Writing Record.pdf” in the book’s build folder, and opens it when it’s made. It has these sections:

Words are counted in the book’s scenes, not the Stash or notes, from one saved version to the next: a version that adds and cuts the same number of words counts as no change. A day with writing is one on which the book’s length changed.

The record says what it can’t show. It shows the history of the book’s files as Septangular saved them, not who was at the keyboard, and its dates come from the computer’s clock. To check a record against the book, open the book, go to Versions and find the version whose fingerprint matches the record’s “Latest version”. If the book has been saved since the record was made, that version is still in the list, with the same fingerprint.

In a series, the history is the series’, so a book’s writing record counts every version and session of the series, while its words are the book’s own.

Where the history is kept

The history lives inside the book’s own folder, in a hidden folder called .septangular/versions. It needs no internet connection, account or other program, and it’s kept apart from anything else on your computer. Back the book’s folder up, and its history goes with it. Don’t delete the .septangular folder: it holds the history. Appendix C describes the folder in full.

For a book in a series, the history is in the series folder, and covers every book in the series and the shared Story Bible: a save in any book is a version of the whole series, and a snapshot names that version for all of them.

What the history leaves out

Every file in the book’s folder is kept in each version, except:

• the folders and files that the book’s builds are written to, as its configurations name them (see Chapter 9), so finished PDFs and ebooks don’t fill the history;
• the .septangular folder itself, which holds the history and Septangular’s own settings for the book;
• a folder called snapshots at the top of the book’s folder;
• files the Mac and other programs leave behind: .DS_Store, Thumbs.db, and files whose names end in ~ or begin with .~lock..

Statistics reads its figures from the same history, as Chapter 7 explains.