This is a technical overview of how to use set up Scrivener documents for use with the free content versioning system Subversion.
It combines a basic description of adding a Scrivener document to an svn repository with two advanced gotchas - the need to cache .svn data, and potential problems with the binder file. It also assumes that:
- You already know the very basics of subversion
- You already have subversion client tools installed locally, and already have permissions to create a subversion repository somewhere else.
- You have a Scrivener document that you want to track changes on and/or collaborate on.
SETTING UP SUBVERSION+SCRIVENER
During this process, do not run Scrivener (for reasons discussed in “Working” below).
Create your subversion repository, “scrivenerdocs,” which will hold all your collaboratively authored Scrivener documents (for example, on a remote server). In Terminal:
svnadmin create scrivenerdocs
Note that some hosts allow this step via control panel.
Check out a blank working copy from the server repository to any place on your hard drive - for example, a special section of your user folder. In Terminal:
svn co [svn+ssh://email@example.com/mydirectory/scrivenerdocs](svn+ssh://firstname.lastname@example.org/mydirectory/scrivenerdocs) ~/subversion/checkouts/scrivenerdocs
Add a Scrivener doc to your working copy and mark it as added. In Terminal:
cp -r ~/Documents/MyDocument.scriv ~/subversion/checkouts/scrivenerdocs/
svn add ~/subversion/checkouts/scrivenerdocs/MyDocument.scriv
You can add as many Scrivener docs as you like right away. Note that from now on, the .scriv file in /checkouts will be your active version - the one in /Documents you can delete or archive.
Cache all your .svn folders to another directory (for reasons discussed in “Working” below).
sudo rsync -av --include "*/" --include ".svn/**" --exclude "*"\ ~/subversion/checkouts/scrivenerdocs/ ~/subversion/checkouts/scrivenerdocs-cache
Upload the file to your repository
svn commit ~/subversion/checkouts/scrivenerdocs -m "Initial import of my very first Scrivener file"
Now you can get working - as many people as you like can check out copies and make changes, and all the changes will be tracked and combined. However there are still two big problems:
Problem: Scrivener auto-deletes the .svn subfolders
Deleting these folders breaks any Subversion working copy as soon as the program is run. This is a frustrating problem (as there doesn’t seem to be any reason for it), but it is surmountable. This is why we created a cache of .svn folder data. Every time we checkout, update, or commit, we can restore the cache before doing it, and backup the cache after.
edit in Scrivener
restore .svn from cache
sudo rsync -av --ignore-existing --include "*/" --include ".svn/**" --exclude "*" ~/subversion/checkouts/scrivener-cache/ ~/subversion/checkouts/scrivenerdocs;
update local .svn info, check remote changes, and commit changes to the remote repository
svn status ~/subversion/checkouts/scrivenerdocs
svn update ~/subversion/checkouts/scrivenerdocs
svn commit ~/subversion/checkouts/scrivenerdocs -m "Latest changes"
backup latest .svn to cache
sudo rsync -av --include "*/" --include ".svn/**" --exclude "*"\ ~/subversion/checkouts/scrivenerdocs/ ~/subversion/checkouts/scrivener-cache
Yes, this means that the whole process is more complicated. I’d like to wrap these up in one or two scripts, but I haven’t yet.
Problem: MyDocument.scriv/binder.scrivproj is binary
That means no manually merging the file if someone else has edited the repository. In practice, this means that editing the content of entries is easy, but adding, deleting, moving or deleting entries in the binder creates a potential sync problem - if two collaborators change the binder, then one will blow away the other’s changes, with the second editor either leaving binder entries pointing to missing files that the first deleted or omitting binder entries pointing to orphaned files that the first added.
Currently the only solutions are:
- agree that only one collaborator will perform binder edits, the rest will edit existing documents.
- If a conflict occurs on binder.scrivproj, check out a new working copy and manually merge the two by dragging and dropping resources in Scrivener.
That is a shame, as one big part of the appeal of Scrivener is editing the collection using its binder interface. However the only way that could really change is EITHER if the binder.scrivproj file were text-based OR if the authoritative binder information was stored in the files themselves (e.g. spotlight comments) and the binder was rebuilt dynamically on startup from present assets - in other words, the program as a whole would have to work so differently from how it currently does that it aint gonna happen. Much more likely would be leveraging some merge import or merge function in Scrivener allowing you to combine two Scrivener projects.