Handle screenplay revisions without losing your work

A revision is the moment a production finds out how much of its prep was really filing. New pages arrive, and somewhere a coordinator starts re-entering scene numbers.

SceneMatch treats a revision as a merge, not a re-import. The new draft is matched against the production you already have, you are shown exactly what will change, and only then is anything applied.

Upload, review, then merge

Uploading a revision does not change your production. It opens a review: each scene of the new draft beside the production scene it maps to, tagged with what the merge will do to it, and a count of each tag at the top.

The tag is also a choice where the draft could mean either: a Deleted scene can be switched to Kept, and a New one to Merged Up — or back. The characters the draft introduces are listed above the scenes, and a name you do not want can be ignored rather than added.

Read the review before you commit. It is the only point at which the change is still free, and the counts are usually more informative than the coloured pages themselves: a draft that looks like a handful of edits can report 111 new scenes.

Cancelling leaves everything exactly as it was. Upload a revision, read the review, decide it is not the draft you meant, cancel — your production is untouched, right down to the scene count.

Only one revision can wait for review at a time — per production, or per episode on a season. Accept or reject it before uploading the next.

What an updated scene tells you

An updated scene names only what the merge changes, each with its new value — the current one is in the scene's own header, right beside it:

• A heading detail — Location, Int / Ext, Time of day, Time, Timeline, Scene number or Status (omitted) — with what it becomes, for example Location London. The location is read as it is shown, with its continuity after it — Location Kitchen - Moments Later — so a scene that goes from CONTINUOUS to MOMENTS LATER is listed, and one that only had the word moved out of its location name is not. A location you renamed in the app shows up here on every scene whose slug line still uses the old name, and accepting it puts the script's name back. Capitals you corrected are a different case: see below.
• Description updated — the description is replaced with the new draft's text. Description not updated means the draft's text changed but the description stays, because someone edited it and the upload was set to update only unchanged descriptions. With Don't Update chosen at upload, neither line appears: every description stays, as asked.
• Characters added — characters the new text names that the scene does not have yet.
• Not in script, kept — characters on the scene that the new text no longer names. A revision never takes a character off a scene, so they stay; remove them yourself if they really left it.
• Only the scene script is updated — the text changed and nothing else did: the scene keeps every detail, its description and its characters.

A scene whose content does not change at all is tagged Same instead, so the updated ones are exactly the scenes worth reading.

Full script or partial script

Not every revision is a whole new draft. Often what arrives is a handful of coloured pages, or one scene rewritten the night before. So when you upload a script to a production that already has scenes, the form asks what the file holds:

A partial script goes through the same review and merge as a full one. The difference is only in what missing means: the scenes in the file are updated or added, and nothing else is touched. A partial script never deletes a scene — if the pages drop one, remove it yourself or wait for the next full draft.

Choose carefully, because the two mistakes are not equally visible. A partial file uploaded as a full script is loud: the review marks everything the pages do not carry as deleted, and the merge will not go ahead without your confirmation. A full draft uploaded as a partial script is quiet — the scenes the draft cut simply stay, and nothing in the review tells you they should have gone.

Revision pages are pages, not scenes, and a page often starts partway through a scene. An update replaces a scene's whole script with what the file holds, so a scene that is only partly on the pages will be updated to that part. Read the updated scenes in the review before you accept, and upload any scene that is cut short on its own instead.

Revising a single scene

When only one scene changed, you can upload it from the scene itself: open the scene's actions menu and choose Upload Scene Script. It is a partial script with the guesswork taken out:

• It updates the scene you uploaded from, whatever number the file puts on it. A page with a single heading and no scene number is fine; SceneMatch does not have to match anything.
• A file with more than one scene is narrowed down to the one numbered like the scene you are revising — a page that also carries the end of the scene before it, say. If no scene in the file has that number, the upload stops and tells you, rather than guessing which one you meant.
• You decide about the description. A full script can update only the descriptions you have not edited; for a single scene you know whether you did, so the choice is simply update or leave it — and it starts on leaving it.
• The review opens straight away, so the whole change is upload, check, accept.

It is still a revision like any other: it takes a revision colour, appears in the revision history, and waits for review — so it also counts as the one pending revision for the production or episode.

Deletions ask twice

When a revision would remove scenes, SceneMatch does not just apply it. The merge pauses and asks you to type DELETE before it goes ahead, because a deleted scene takes its work with it. It is a word rather than a checkbox so that it cannot be clicked through on the way to the button; case does not matter, so a phone capitalising the first letter is fine.

Every scene tagged Deleted lists what goes with it, so the scenes that carry work stand out before you get to the confirmation:

A scene with nothing attached says so. The confirmation then adds it all up, and lists every deleted scene with its own share underneath, so a large total can be traced to the scenes it comes from. Photos, notes, takes and annotations are the part you cannot get back: nothing in the revision history restores them. If any of those appear, someone did work on a scene the new draft has dropped.

A revision that adds and updates but removes nothing merges in one step, with no second prompt — which is every partial script.

One thing worth knowing: a scene the new draft marks as omitted is not the same as a scene the new draft has dropped. An omitted scene is still matched and updated — it is flagged omitted and its filming state is cleared, but the scene stays in your production and keeps everything attached to it.

What survives a merge

This is the part worth trusting, because it is where the re-typing usually happens:

• Filming states. Scenes you have marked fully or partially filmed keep those marks. A scene marked filmed before a revision is still marked filmed after it, under its new content.
• Script days. An auto-generated timeline survives the merge with its days intact, and new scenes are absorbed into the days they belong to. Twenty-eight script days before a revision are twenty-eight after it.
• Characters. Existing characters are matched, not duplicated. Only genuinely new names are created, and the review lists them.
• Images and notes. Everything attached to a scene stays attached. A scene that is updated by the revision takes the new draft's content, but its reference images and its notes are untouched — they belong to the scene, not to the draft that created it.
• Images and notes on a character in a scene. The same holds one level down. What you have attached to a character inside a specific scene survives that scene being updated, and it survives even if the new draft no longer mentions that character in the scene — the character is not stripped out of a scene by a revision, so nothing hanging off it is lost.
• Corrected capitals. A location you re-capitalised — Fbi Hq made FBI HQ — keeps your capitals through a revision whose slug line still names the same place, and is not listed as a change. A location the new draft actually renames takes the new name, written as an import writes it.
• Looks. A look belongs to the character, not to the scene, so no revision can delete one. Looks stay attached to the scenes they cover through an update — and they survive a deletion too. When scenes go, the look itself is untouched, photos and details and wardrobe intact; those scenes simply drop out of its continuity coverage, exactly as if you had detached them by hand on the look itself.

Deletion is the only thing that removes attached work, and looks are its one exception.

Screenplay annotations follow their own rules — see what happens to annotations in a revision.

A scene you mark to keep, rather than delete, keeps its script as well as its work: the new draft has nothing for it, so it goes on showing the text it had.

Reading the revision history

The script page lists every revision with its colour, whether it was a Full Script or a Partial Script, who uploaded it and when, and how many scenes and characters it added or removed. The file itself stays in the production's documents, one click away from its entry.

In the script viewer, each scene carries the colour and date of the revision that last changed it. After a full draft that is the same for every scene; after revision pages, only the scenes on those pages take the new colour and the rest keep theirs — the way coloured pages work on paper. Earlier versions of a scene are not kept once a newer one replaces it; the uploaded file in documents is the record of what a draft said.

The revision colour comes from the file name

The revision colour is a field on the upload form, and SceneMatch fills it in for you by reading the name of the file you picked — choose Watcher_pink.pdf and the form comes back set to Pink before you have uploaded anything. The colour printed on the pages themselves is not read; nothing inside the script is inspected for it.

Two consequences are worth knowing before you name a file:

• Only the English colour names are recognised — white, blue, pink, yellow, green, goldenrod, buff, salmon, cherry, tan and ivory. A French draft named rose or a German one named blau arrives with no colour preselected. The script is still imported and merged exactly the same way; only the colour label is left for you to choose.
• It is a plain match on the name. The colour word has to appear somewhere after the first character — script_pink.pdf is recognised, a file named just pink.pdf is not — and any word containing a colour name counts, so a draft named after a character called Stan will offer you Tan.

The field is always editable, whatever SceneMatch guessed or failed to guess. Set it before you upload and the revision history reads the way the production talks — "the pink pages" — rather than as upload timestamps. If you work in another language, either put the English colour in the file name or just pick it from the list each time.

The thing that is not obvious

Scene numbers are how the merge matches. A scene that keeps its number is updated in place and keeps everything attached to it. A scene whose number changes is, as far as a full draft is concerned, a deletion and an addition — the old one goes, a new one arrives empty. On revision pages it is only an addition: the renumbered scene arrives as new, and the old one stays until you remove it. The one upload that does not match by number is a single scene uploaded from the scene itself.

So a renumbering pass between drafts is far more expensive than it looks: it is the one kind of change that costs you attached work. If a scene is being renumbered in the script, expect to redo its continuity rather than assuming the merge will carry it across.

Before you merge a heavy revision

Read the Deleted count first. Everything else in the review is additive and cheap to correct. If that number is large, read what each deleted scene lists before confirming, and switch any scene the draft should not have dropped to Kept.