Scrivener and Subversion?

Does anybody else use Subversion? I keep my rag-tag collection of writing files in it, to sync between two computers and also for the version control.

But, I’m having some problems with some Scrivener files. I know that Scrivener stores everything in individual files inside the .scriv package, but some of those individual files are reporting locking problems that I’m unable to resolve, so it’s frustratingly blocking my check-ins.

Any Subversion whizzes out there know of what I speak?


Potentially dumb question, but you do not happen to have the Scrivener project open while attempting to synch, do you?

There are no dumb questions! Not in my case anyway.

But I can clarify that indeed the files were closed, as was Scrivener, before I tried to do any Subversion stuff from the command line. Usually my first order of business after editing a file was to run a “svn status” just to see if I need to add any files. If so, I’d add them.

After a few successful check in and outs, I was getting the tilde in my status reports on certain files, suggesting they were locked or being used by another file. Those files couldn’t be added, locked, unlocked or removed. Running a cleanup wasn’t successful either.

It’s like they are being used by another program that is interfering with Subversion (or maybe the creation of the .svn folders?)

Your are right on the money. :wink:
I just tried ‘svn status’ on my test-project written in Scrivener, all folders from the initial import/first checkout phase have no .svn folder, which should be inside of them. svn complains that the folder is already under its control but .svn is missing:

‘/4.rtfd/.svn’ containing working copy admin area is missing’

My best guess at the moment is, that one of the Frameworks used by Scrivener “cleaned” them out of the rtfd folders.

Start nerdy hint for Keith:
Looks like ‘AppKit’ is to blame (a quick guess after a glance at the documentation in Xcode). Maybe one of the functions uses a filter for file-types that are allowed to be in a .rtfd?
End nerdy hint for Keith 8)

If I should figure something out, I’ll post it here.

BTW: I’m very impressed with Scrivener, looks like I really might abandon the emacs/docbook combo I used for three books so far. I have to figure out a way to convert the final draft into XML, though.


MultiMarkdown is really what you want, in that case. Scrivener without it produces an export entirely devoid of structure, and it would be extremely difficult to get that into a structural XML file. Using MMD->XHTML would give you an XML file that you could then transform using any variety of the XSLTs available on the 'net for XHTML. The one drawback is that it does not produce a hierarchal structure. In other words, a chapter heading is defined, then a paragraph is defined, then a chapter heading, and so on – all on the same level. The Perl script that generates the XSLT could be modified to do something like:




[/code] That would make the conversion with XSLTs a lot easier for some purposes.

Note that editing the individual files within the .scriv package in another application is not really recommended, and certainly not supported. :slight_smile:

I guess my support request has turned into a feature request: Keith, I would like to be able to use .scriv files with Subversion. In the meantime, I’m just zipping up every revision to share back and forth.

It’s a bit of a pain, but worth it to use such a cool product.

I guess that was meant for me :wink: . I don’t intend to modify the files, I was thinking in the lines of some utility which could “resurrect” the missing .svn folders based on information of the enclosing folder’s .svn.

@AmberV: Thanks for the hint. I think I’ll be either, able to find an XSLT to transform XHTML to docbook-XML the way I need it, or, (in the spirit of this site) given a decent supply of Latte from my Espresso-machine, I’ll do it myself. Might be more fun actually, to do it myself. I have to cater to my reputation as “writing geek” anyway. 8)

@Keith: The program is awesome.


My espresso machine is about to break, which is a somewhat scary thing, given all of that high pressure scalding steam.

So that’s where all the steam on the forum is coming from. It’s your fault.



Actually it was just the developer’s standard “don’t blame me if your computer blows up” caveat. :slight_smile:

Thanks. :slight_smile:

I have to admit that I’m not really sure of the issues with Subversion, as I don’t really use it. Is the problem just that it doesn’t play well with folders (given that .scriv files are just folders)? If so, there’s not much I can do about that, I’m afraid.

Sorry if I’m a bit vague - it’s my son’s third birthday, so I haven’t been following discussions as closely today as I usually do…

The one with the big nose? Wish him a happy birthday from us.


Lol! :slight_smile: You’ve got a good memory!

P.S. To other readers of this post: just for the record, my son has not got a big nose. This is a reference to a discussion about… Oh, nevermind, I have Cava to open.

@Keith: Not sure which timezone you’re in, but if your son is still awake, get back to him. :slight_smile:

I’ll try to do some research into the whole .svn-thing tomorrow, if I can find the time. If something usable pops up, I’ll let you know.

If I can get this to work, I might convince my editor to use Scrivener as well, we then could bounce the .scrivs back and forth and forget about sending PDFs or XML-Files; we would just do check-ins and check-outs in subversion.


SVN handles folders just fine. I think it may be either SVN or the OS hosting SVN does not recognise some of the folder attributes that defines it as a package. That’s my guess anyway since it is the only thing that stands out between regular folders/files vs. unit packages.

Three year olds are great - 3 to 5 is the golden age.

I just tried to do the same thing last week - I friend and I wanted to see if we could collaborate with a team - each person would buy scrivener and we would check our changes in and out of the subversion repository. Given that a scrivener document is essentially a folder full of little files, it seemed ideal - way better than playing the track changes game with Microsoft Word.

But I ran into the same hitch you did. I believe that subversion stores absolutely everything in directories named .svn - one per folder. You’d probably want to do something like this.

  1. Close Scrivener.
  2. Check the document in to subversion.
  3. Check out a working copy.
  4. Run a backup shell script / folder synchronizer, but only copy the .svn directories.
  5. Edit Scrivener.
  6. When you want to update, close Scrivener
  7. Run a restore shell script, copying the .ssh directories back.
  8. Use svn or a subversion client to register your changes and commit to the server.

The alternative is to wheedle Kevin into exempting the .svn folders from the purge - no clue how hard that would be though (the exemption OR the wheedling). :smiley:

I’ll probably let it lie for a while before I dust myself off and try to write a shell script and make it a droplet. Still, team-manuscript editing with scrivener does sound like fun…

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:

  1. You already know the very basics of subversion
  2. You already have subversion client tools installed locally, and already have permissions to create a subversion repository somewhere else.
  3. You have a Scrivener document that you want to track changes on and/or collaborate on.


During this process, do not run Scrivener (for reasons discussed in “Working” below).

  1. Create your subversion repository, “scrivenerdocs,” which will hold all your collaboratively authored Scrivener documents (for example, on a remote server). In Terminal:

     ssh [](  
     cd mydirectory  
     svnadmin create scrivenerdocs  

    Note that some hosts allow this step via control panel.

  2. 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:

     cd ~
     mkdir subversion
     mkdir subversion/checkouts
     svn co [svn+ssh://](svn+ssh:// ~/subversion/checkouts/scrivenerdocs
  3. 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.

  4. 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
  5. 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.

  1. edit in Scrivener

  2. close Scrivener

  3. restore .svn from cache

     sudo rsync -av --ignore-existing --include "*/" --include ".svn/**" --exclude "*" ~/subversion/checkouts/scrivener-cache/ ~/subversion/checkouts/scrivenerdocs;
  4. 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"
  5. 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:

  1. agree that only one collaborator will perform binder edits, the rest will edit existing documents.
  2. 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.

Great post Jeremy! I think an initial and relatively simple fix that Keith could make would be to stop Scrivener from removing the “.svn” directories. This is possibly easier than having you write scripts to automate the caching of these directories.

The binding update issue is always going to be problematic. Concurrent updates to the project/document structure will always lead to inconsistencies that can only be addressed by a human user. As long as people understand this when they’re collaboratively editing, then you can implement processes/controls to make sure it doesn’t happen. The other solution is a user-driven merge, but this is a non-trivial undertaking.

Hmm, I’m not sure what you mean - there is no code in Scrivener that removes any .svn directories or anything else that it doesn’t know about within the package. Weird.