Synchronised Folders

Scrivener's "Sync with External Folder" feature allows you to sync the text contents of a project with the contents of an external folder stored on disk. Using this feature, you can share your work in progress with collaborators, agents, or editors using common text file formats, and easily incorporate any changes they have made back into your project (for instance by storing the external folder in a folder that you share with others via Dropbox).

Important Note
This feature is not intended (and will not work) for syncing with the iOS version of Scrivener. For that, you simply place the entire project in the sync folder you have set up on iOS. Neither is this feature intended for keeping two versions of the same project in sync across different computers - you should never try to sync two different projects with the same folder. Rather, this feature is intended to allow you to edit or share project files with other applications, and then have any changes made to the shared files merged back into your Scrivener project.

## Setting it Up

To access the feature, select `Sync ▸ with External Folder...` from the `File` menu. The panel pictured below will appear.

The first thing you will need to do is select a new, empty folder which Scrivener will use for syncing files with this project. Click the `Choose...` button and navigate to the folder you want to use (for instance, a folder on Dropbox). Keep in mind that the folder you create will need to be dedicated to this Scrivener project, and so must be initially empty. When you sync documents with this folder, Scrivener will create one or more of the following three subdirectories to store the synced files:

- “Draft” - stores documents contained inside Scrivener's Draft folder.
- “Notes” - stores text documents contained elsewhere in the project.
- “Trashed Files” - stores documents that had been synced but have since been removed from Scrivener, or which had some sort of conflict. You should occasionally review these files and trash them if they are no longer required.

Do not select a folder which has already been used to synchronise another Scrivener project! The only time you should choose an existing Scrivener sync folder is if you are certain it is for the same project, and that you have total control over the project (it isn't being edited by anyone else with a copy of the project). Usually, this will only ever be the case if you are moving the project to a new computer.

Using this feature in an attempt to merge projects, or to have more than one person using a copy of the project, could result in lost data or confusing results. When in doubt, always create a new folder.

Next, go through the various options:

Sync the contents of the Draft folder

  Enabled by default, the entire Draft folder will be kept in sync with the folder when this is on.

Sync all other text documents in the project

  Keep the rest of the project up-to-date with this option. Note it will only work with text files. Enabling this option also activates the Import settings (see below).

Sync only documents in collection

  If this is selected, only documents that are contained in the collection specified in the pop-up list next to this checkbox will be kept in sync with the folder. This acts as a filter for the two above “Sync” options. For instance, if “Sync the contents of the Draft folder” is selected but “Sync all other text documents” is not, and if this option is selected, then only documents that are contained in the Draft folder and in the specified collection will be synced.

Prefix file names with numbers

  By default, Scrivener will prefix each file name with a numeral corresponding to its position in the Binder. This will keep your files in the same order as the Binder, making them easier to find. Disabling this will remove the number and the contents of the folder will be subject to ordinary alphanumeric sorting based on the names of your Binder items.

Take snapshots of affected documents before updating

  With this option turned on, Scrivener will automatically generate snapshots of each document if it requires updating.

Check for changes in external folder on project open and automatically sync on close

  If ticked, when the project is opened it will scan the contents of the external sync folder and alert you if there are any changes detected, offering you the ability to update your project immediately. It will also automatically sync any changes in the project to the external folder when the project is closed.

The Import section allows you to choose where files that have been created in the "Notes" folder outside of Scrivener will be imported. (Files created in the "Draft" folder will be imported into the Draft folder, of course.) You can select a target container (Research by default), or uncheck the “Only show containers in destination list” option to choose any item to become a container for imported files. This section will be disabled if “Sync all other text documents in the project” is turned off.

The Format section determines how the files will be created in the sync folder. Because script writers might not want to use a script format for notes and research documents, there are separate options for files stored in the Draft folder and other files in the project.

- Plain Text (TXT): Files in the external folder will be standard, plain text files in the UTF–8 format (stripped of all formatting). If they are edited outside of Scrivener, when synced back in, all formatting in paragraphs that have been edited will be lost. If formatting is important to your workflow, you should not use this option and instead choose RTF.

  When plain text is the chosen format, you can change the default extension that Scrivener will use for the exported files. If you use an editor that displays markup, for example, it can be handy to change the extension to the markup’s accepted form, such as .md for Markdown.

- Rich Text (RTF): This is usually the best option. Most formatting will be retained (excepting styles), especially when used in conjunction with a word processor that handles all of Scrivener’s RTF features, such as Word or Nisus Writer. This is the best option for collaborating with other individuals who do not have access to Scrivener. All desktop versions of Microsoft Word fully support the RTF format.

- Final Draft (FDX): Those working on scripts and wishing to share files with a Final Draft user should use this option.

- Fountain (.fountain): For use with screenplays, this popular plain text markup format can be edited anywhere plain text files can be edited, and so has a similar appeal to Markdown for its portability. Scrivener’s internal scriptwriting format will be converted to Fountain syntax when updating the folder contents, and then in reverse the syntax will be converted to Scrivener elements when updating the project. Additional formatting supported by Fountain markup will be converted as well. For details, read more about working with Fountain in the user manual PDF, in the chapter on scriptwriting.

  Only those binder items set to use scriptwriting mode will be converted to Fountain. Standard text documents in the binder will be synced as plain text documents. Any new text documents added to the “Draft” sync folder from outside of Scrivener will be assumed as Fountain format.

Automatically convert plain text paragraph spacing

  When this option is engaged, Scrivener will intelligently convert your documents' paragraph spacing to better suit the intended environment. Since Plain text editors cannot display pseudo-spacing between paragraphs, this option will insert a second carriage return to help set them apart from one another. Upon import, these extra carriage returns will be removed for you.

Keep this setting turned off if you require a certain standard, one way or the other, and do not want Scrivener to adjust things for you. In particular, those working in the MultiMarkdown workflow require double-spaced paragraphs, and so will not want Scrivener to remove these spacings upon import. Note that this option only affects plain text (TXT) documents.

Additional settings which impact export and import can be found in the application preferences, under `Sharing`.

## Usage

After clicking the `Sync` button for the first time, Scrivener will export a copy of every item to the external folder, according to the options above. Scrivener will export all items associated with your manuscript into the `Draft` folder. If you choose to export non-Draft files, everything else will be placed into the `Notes` folder.

In a collaboration environment, it is safe for you to work in the project at the same time as your collaborator works on the exported copies, so long as changed files are looked over after syncing. In most cases Scrivener will select the best option for you, but in cases where both you and your colleague have changed the file in between syncs, you might need to resolve the differences using Snapshots and the Compare feature.

When performing a folder sync, only resources which have changed (either in the project or on the disk) will be synchronised. In the case where project Binder items have been updated from the disk, a list of these changed items will be presented to you upon completion. Use this tool to browse through the changed items and review them with the Snapshot Compare feature. This interface is much like Project Search, and can be dismissed by clicking the `X` button in the left of the Binder header bar.

For those that want to dig a little deeper, this is really a Collection that will be created and titled “Updated Documents”, with each changed document added to it. Every time sync needs to change project files, it will look for a Collection named “Updated Documents”, and replace the contents of it with the results of the latest sync, so if you wish to retain a list of changed files for future reference, change the name of the Collection to something else.

New files can be created while you are away from your project. Simply name them whatever you would like them to be called in the Binder, and save them to the "Draft" or "Notes" folder. Scrivener will import files created in the external "Draft" folder into the project's Draft folder, and files created in the external "Notes" folder into the designated container (Research by default) when you sync.

When you have returned to your computer and wish to incorporate any of the changes made, simply load the project in Scrivener. It will, by default, check for any changed files and alert you that your project needs updating. If you have this option disabled, or the project is already open, you can manually activate the sync panel again, using the menu item, and click the `Sync` button.

## Tips for Working with Synced Folders

Here are a few guidelines which, if followed, will prevent problems in everyday use:

- Alternate between external files and the project. This is a rule of thumb, not a strict rule. Scrivener reads the modification date of each file, and uses the latest one to determine which should be the Binder copy. It does not examine the contents of files. It is thus best to alternate between using the external files, and the project folder, rather than working in both separately for a while, and trying to merge them later.
- Never try to sync one project's folder with another. Even if those two projects originally came from the same identical project, over time there will be differences in each project that you cannot see, and these differences will lead to confusing results at the best, and a loss of data at the worst. A sync folder is meant to allow you to work without Scrivener for a while, and then come back later and update your project with those changes. If you try to break this rule, you will be warned by a dialogue box.
- When working from multiple computers sharing the same sync folder, always make sure your project file is the most current. It is perfectly safe to use the same project to sync to a shared folder from multiple computers provided you are always using the most recent version of the project and are not trying to bend the feature to sync two different versions of the project (see above). You will receive a warning dialogue the first time you try on each system, but in this one case it can be ignored.
- Generally, try to avoid editing the file name. The numeric value at the end of the file name enclosed in square brackets, such as “[78]” (the precise number will be different for each item), is vital to keeping the file linked with a document in the project; damaging the number could produce unintended duplication, or data loss in some cases. (You can safely edit the rest of the file name so long as you don't touch the number or the square brackets, however - this will rename the document when syncing back to Scrivener.)
- Session target goals will include synced changes. When updating project files with external edits, the session target will be incremented by the amount of text that has been added. If you wish to keep track of your session target separately, you might wish to reset the counter after updating your project.
- If using mixed Inspector comments and inline annotations: When using sync folders, it is best to use either all Inspector footnotes and comments, or all inline annotations and footnotes, and set your Sharing preferences accordingly. In some rare cases, comments adjacent to annotations can result in one of the notes getting lost, due to the limitations of the RTF format.

If you are using this feature in conjunction with another author or editor, make sure to communicate these ground rules with them where relevant. Since it is not possible for Scrivener to guess at your intentions, good communication over where new files should go, and what is being independently worked upon, will be beneficial.

## Limitations

RTF Format Limitations: When using the RTF export format, you can expect zero to minimal loss of formatting information when used in conjunction with a good word processor. There are a few features in Scrivener that have no comparison in RTF, such as multi-colour annotations and comments, and internal document links, which will be normalised or lost, however. Also, styles in a document will be lost when using external folder sync. (Note that formatting will all be retained, but the styles associated with formatting will no longer be recognised.)

- If you use sequential annotations separated only by colour, it would be a good idea to move them so that they have a word or two in between them, or separate them by putting them on different lines.
- Expect loss of some features when using RTF editors that do not fully support the RTF specifications, such as TextEdit. Footnotes, comments, lists, images and tables are the most common items which have limited support. Using fully-featured word processors with good RTF support, such as Word or Nisus Writer Pro, will help you avoid issues.

Plain text Limitations: Since it is impossible to convey formatting in plain text without some sort of visible mark-up, Scrivener takes steps to protect as much of your formatting as it can. As with RTF, only those files which have been edited will be transferred back to your project. Further, each changed file will be analysed at the paragraph level and Scrivener will only replace those paragraphs that have been changed, leaving the rest of the file untouched with its original formatting.

- To avoid having inline notation become confused with standard text, Scrivener will export inline annotations by wrapping them in square (`[` and `]`) brackets. Inline footnotes will be wrapped in curly braces (`{` and `}`). However, since Scrivener only updates changed paragraphs, unless you edit a paragraph with one of these types, no loss of notation should occur in the rest of the document. In the case that you do edit a paragraph with notes in it, the bracket notation will be retained so that you can manually fix the formatting. A helpful tip to remember is that you can copy and paste from snapshots.
- Inspector comments and footnotes will not be exported. If the retention of this information is important to you, it is recommended you use inline notation with plain text. You can easily convert your notes to inline with the `Format ▸ Convert` tools.
- Inline images will be stripped from documents that have been edited outside of Scrivener.