Did you once depend on Adobe Version Cue, but would have preferred a simpler, problem-free system? Don't have time for a complicated revision control system? If all you need is to check files in and out in a sane, safe, simple manner, then consider Grapple.

For several years the team at Himalayan Academy Publications used Adobe Version Cue to manage the publication files we worked on as a team using Adobe InDesign. When Version Cue came out, it was actually a huge blessing, for we previously had no way to manage multiple people working on a set of files on our local file server, and that condition came with its own set of problems, of course. Version Cue had it's quirks, but we needed it.

In April 2010, just before Adobe announced CS5, we were hopeful. Version Cue CS4 had been nightmarishly riddled with problems, while CS3 had been their most stable, nearly problem-free version yet. We had hoped that in CS5 they would have gone back to their Version Cue CS3 code base and give us something that worked again. But they didn't do that. Instead, with the CS5 announcement, they told the world that they were discontinuing Version Cue and that we would have to "purchase a DAM system for this purpose" (as they put it; DAM stands for Digital Asset Management) from another vendor. We were faced with a dilemma, because we wanted to upgrade to CS5 to take advantage of new features, but we couldn't afford to lose the versioning capability, and nobody had come out with a commercial replacement for Version Cue using Adobe's APIs yet.

A member of our team has been writing in-house applications using RunRev's LiveCode for many years. We already had libraries for web content deployment which automated processes of moving, copying and renaming files at the file system level. In a pinch, he created a simple application to do the job. Grapple was born. Right away, it worked.

Grapple is an uncomplicated application. It uses the Unix shell commands "cp" and "mv" to copy, rename and relocate files. The interface serves as a window on InDesign files in project folders on a central Mac OS X Server. In the application, a user can choose from available projects, see the status of the files, check out and open files, check files back in. That's about it. That's all we needed, so we kept it that simple. This makes it easy to use, with no administrative overhead, no database to install or maintain. It does the job and doesn't get in the way. We have tested it, lived with it and used it for our Hinduism Today magazine production cycles for six months, and we have found it to be effective for our needs.

Disclaimer: Grapple's simplicity is also its vulnerability. The application makes no attempts to be a police officer. Files under Grapple's control are also freely available in the Finder. Grapple assumes that your team is mature enough to work by a professional code of conduct and not manually tamper with the repository of files in the Finder. More on that below. To get started, we recommend you watch the how-to video first, then download the standalone application, set up the folder on your server, and give Grapple a try.

 

Terms of Use

Built with:
  LiveCode   from Runrev.com

The standalone Grapple application available here was compiled with a LiveCode educational license and must only be deployed or passed along free of charge.

The source stacks are available under a modified MIT license. Anyone with a LiveCode license can modify and use the stacks freely. If you have a professional LiveCode license, feel free (in fact we encourage you) to recompile and release the software under your own name, in which case you may charge for it if you wish. Another model might be to distribute the application for free and then charge for your services to customize the application. The MIT license does not require you to contribute your updates back to the community, but you are encouraged to do so.

We provide no warranty, no support or promise of further development or patches for Grapple. For support or customization, please contact a LiveCode programmer of your choosing. For a full disclaimer, please see the About screen in the Grapple application.

Download

All you need is the application:

Source Code for LiveCode Developers:

Overview, Installation and User Manual

Basic components

The Grapple revision control system for InDesign is comprised of three components:

  1. A folder called "Grapple Version Control" on a server or mountable volume on the LAN that can be accessed by all authorized editors where it is assumed to have an IP and requires both a user name and password for access. This is set up by the administrator (more below.)
  2. The desktop application called "Grapple"
  3. A folder on the local computer in the user home folder's Documents folder called "Grapple Local Version Control" which is set up automatically by Grapple.

Installation

Server Setup:

  1. Make the Grapple Version Control folder on the server. A team member needs to create a folder called "Grapple Version Control" on an existing server sharepoint (It could be any name but this is recommended, Your server admin may need to help if you do not have permissions to create such a folder.). In our theoretical example this will appear to the client stations with a path like this:

      /Volumes/Editorial (this is the server sharepoint mounted on the local file system)
         /Grapple Version Control (this is the new folder; it must have read and write permissions for the users who will access it over the network).

  2. Create ping.txt file. Inside the Grapple Version Control folder, create a plain text file (use Text Edit, or BBEdit or Text Mate) with a single line with the word "true" on it... and no return after that line. Save this to the new Grapple Version Control folder and make sure it has full read permissions: rw-rw-rw

    Please test: From any client station with the server volume mounted on the desktop ("Editorial" in this example... appears like a drive on the desktop), you should be able to run, in terminal:

         cat "/Volumes/Editorial/Grapple Version Control/ping.txt"

    and the result will be "true"

  3. Issue log in credentials: The team probably already has these. If not, send a user name and password to all editors who need to mount the volume on their desktop ii) send them also the IP of the server on the network. These will be needed for each editor to fill in preferences. If you have some "naive users" (who's station's server access was set up for them in advance and they have no idea about credentials because "it just works.") Admin may need stand by as they boot Grapple and help them fill in their preferences

Download the Grapple.app.zip file above. Deploy to all editors. Each one unzips it and puts it into their applications folder. That's all there is to it.

How does it work?

Grapple provides an interface to projects and files on the server and uses the unix shell commands "cp" and "mv" under the hood to perform the following operations:

  1. Make and view folders on the server for "projects" where each folder contains many files for a single "job".
  2. Adds a revision control string ("RC string") to the filename of files newly added to projects. More about this later, but the RC string appended to the filename comprises the sole and complete metadata for the system.
  3. Copies checked in files to the server and updates the RC string accordingly
  4. Copies checked out files from the server to the user's Grapple Local Version Control folder, and updates the RC string accordingly
  5. Blocks certain operations on checked in, or checked out files, as required for revision control.
  6. Gives the option to rename the files from inside Grapple (and update filenames in multiple locations)
  7. Provide the option to introduce a file from "outside" grapple as the latest revision (There are typically three special "use cases" when this needed.)
  8. Prevents any catastrophic loss. Recovery is always possible How? Grapple *never-ever* uses the unix command "rm" which means remove or delete. Why? because
    i) this is both a dangerous command in terms of a failure to point to the right file or directory (it could delete entire folders!) and
    ii) Grapple's "super redundancy" policy is "never delete data," always save every instance and every revision of every file.

    File corruption or "unprofessional conduct" (Editor A starts editing files checked out by Editor B) can always be rectified, because you can always find a good copy of an earlier revision on the server or in someone's local repository. So, this means recovery is done manually. Your team identifies the revision that should be reinstated as the current version and adds it back to the server with the "Add New Version" function (see video)

About the Revision Control String

Imagine that we are writing a book and the book comprises many files. The book is named "Fish Pond" and we have a general consensus among the team to use a rational file nomenclature. All files will begin with "fish-pond" in the server project folder /Volumes/My Company Files/Grapple Version Control/Fish Pond/ . Let's say that Rajan Sinnathamby, whose initials are "RS," is responsible for a chapter on "Maintenance" and he has a file:

fish-pond maintenance.indd

When he adds this file to the project via Grapple, Grapple will automatically change the file name to:

fish-pond maintenance_r1-ci-RS.indd

Note the string that has been added to the end of the filename before the extension. This is the revision control string, which is a crucial point in Grapple's functionality.

The revision control string begins with an underscore and comprises three segments separated two hyphens:

When a file is checked out the RC String is changed to look like this:

fish-pond maintenance_r2-co-KT.indd

Note that the middle segment has two possible values: ci denotes that the file is checked in and co denotes that the file is checked out.

Limitations:

This version of Grapple does not handle any file type other than InDesign files. Although the internal code framework could, with some work, support other file types, such as Photoshop and Illustrator files, we have not needed this in our shop, so we specifically programmed it to exclude any non-InDesign files. However, a competent LiveCode programmer could easily add the functionality to make Grapple function with any or all file types.

There is no option for comments. There are no invisible files, no database, no semaphore files. Grapple does not offer an interface to roll back to an earlier version. In our experience if there is trouble, editors need to stop, huddle and look at files manually to determine how best to proceed; an automatic widget can hinder or fumble this process difficult. On the other hand, Grapple does allow editors to re-instate any InDesign file as the latest version; all previous versions, of course, will still be available in the project's Versions Archive folder.

Grapple does not attempt to act as a policeman. It assumes mature, professional actors on the stage. If players on the team break the rules, they can break the system. The filename itself is the sole key and potential failure point, i.e. if users start manually fiddling in the Finder with the names of files under revision control they will break the system. On the other hand, if everyone behaves professionally then the failure and bug issues of the system drop to near zero, because there are no external software dependencies. [Note on video: We have subsequently named the folder on the server "Grapple Version Control" and the local folder "Grapple Local Version Control."]

Grapple Rules of Professional Conduct:

There are five basic "do not" rules to follow.

  1. Do not manually remove files from the Grapple Version Control folder on the server or the Grapple Local Version Control folder on any client computer until the project is complete, no one is editing files and the project is ready to be archived.
  2. Do not edit files that are not checked out by yourself. Talk to the owner of the file first! This is probably the most important rule. If you see "_r5-co-RS" and you are not "RS" then don't edit the file. Talk to RS first. Ask them to check the file in and *then* check it out. Grapple has some checks to help prevent this, but these can be over-ridden.
  3. Do not open files in the Finder directly from the server Grapple Version Control folder over network. InDesign files may appear to behave if you open them over the network, but if you open a file on /Volumes/My Company Files/Grapple Version Control/Fish Pond/ from the Finder you risk two negative possibilities:

    i) You have effectively checked out the file, but no one else on the team will see this in Grapple, because you didn't use Grapple to do it. If another user checks out the file while you have it open, you end up with two versions. Depending on the timing, your work or the other editor's work will appear lost (it's not really lost as the files are there in the local folders on the server) and you will need to reconcile them.

    ii) You may cause corruption in the file because if you have it open over the network, a "lost packet" failure may cause the file you save to be damaged and unrecoverable. This is the reason for editing only files that have been copied to a hidden folder on the client's local file system and is one of the reasons Adobe Version Cue was created in the first place (and how it functioned through version CS3). Please, always check out files from inside Grapple and *then* edit them. Grapple automatically copies the file to your hard drive and then launches InDesign.
  4. Do not edit files in your Grapple Local Version Control folder unless they are checked out by you "_r3-co-KT" where you are "KT" and status is "co." If you need to work off line, that's OK. Check out the files you need, and then make very sure you are editing the checked out files in your Grapple Local Version Control folder. Then when you reconnect to the network your workgroup fileserver is on, mount the server and use Grapple to check the files in. If you start editing files that are checked in (e.g. "_r2-ci_RJ") in your local folder, e.g ~/Documents/Grapple Local Version Control/Fish Pond/fish-pond front matter_r2-ci-RJ.indd -- you are editing an old revision and reconciliation of your changes with the current version will be a small or large nightmare.
  5. Do not change filenames outside of Grapple and keep the RC string intact.
    If you need to change the name of a file, do so within Grapple by right-clicking on the filename and choosing the rename option. Be careful not to touch the RC string at the end of the file name: You can change "fish-pond table of contents_r1-ci-RS.indd" to "fish-pond TOC_r1-ci-RS.indd" i.e this portion beginning with the underscore ("_r1-ci-RS.indd") should not be changed.

Change Log

Feature Requests and Bug Reports

To Do:

Send prefs to ~/Library/Preferences/Grapple.prefs, so that these are preserved over upgrades

Implement upgrade routine in the launcher: if grapple.livecode is present and the version number matches the version number on the web, then use it. If grapple.livecode is absent, or the version number on the web is greater, then download and run the new version.

Change Log

November 28th, 2010

Change: "Grapple" added to Names of Folders

Our team felt that the name "Version Control" was too generic. They requested we change the name of the share point on the server to "Grapple Version Control" to make it more recognizable. Actually the name of the share point could be anything the admin wants it to be, but for consistency sake I changed the name of the local folder to "Grapple Local Version Control" which is embedded in several handlers. So, regardless of the choice of folder name on the server the use will always find this:

/Documents/Grapple Local Version Control

________________________

November 24, 2010:

Feature: Security Upgrade

The check in handler's previous method used "rm" to delete the checked out file on the server. This is a dangerous command -- a failure to poke the variable with a proper path, could cause "rm" to fall back to a higher level in the directory level on the server with catastrophic results. Instead, check in now copies the checked out file to the Versions Archive. This is a bit redundant as it is an exact copy of the same olded checked in file, but is safer. Now Grapple lives up to it's stated self-declaration that it does not, underany circumstances, delete any files. Any deletion of files must be done in a manual housekeeping operation later (simply: delete Versions Archive on the server for any project if early files are not needed and users can delete their local Project file which contains obsolete files.)

November 20, 2010:

Feature: Double clickable standalone model implemented.

The http download of the main application layer stack was abandoned. The application layer stack now lives in the application bundle next to the launcher and the launch simple opens it. From the users' view this make is a double clickable app. We did not implement an upgrade path in this version, but LiveCode developers can simply extract the Grapple.livecode stack from the bundle, work on it, and put it back, without having to recompile.

Preferences were also expanded to allow the application to run anywhere. The paths to the server must be set by the user and these are no longer hard coded in the program code. Instead, the preferences are poked runtime into custom properties of the main stack which is then saved. In other words, the preferences are on board the application. Any upgrade (replacement of the grapple.livecode stack) will require the user to re-enter their preferencs an user credentials.

November 9, 2010:

Feature: Add New Version

Functionality added to dialog on clicking a file in the list; no more drag and drop onto a button (which has been removed from the interface. Instead, the user is prompted to choose a file.

Feature: Add New File

Now blocks additions of files with control strings. No attempt is automatically made to try to fix it. The users is informed to manually remove the control string from the file name. Highlighting of the button was fixed to work correctly. It only changes color on a drag operation and reverts when the drag leaves the button area.

Feature - Bug Fix: Auto Create Versions Archive

Previously, Version Archives was only created if the project was created from inside Grapple. If someone manually creates a new project folder in the Versions Control folder on the server and did not create a Versions Archive, Grapple silently ignored the absence of Versions Archive and no versions were archived. No when a projects files are loaded, Grapple checks for the existence of the Versions Archive folder. If none exists it makes one. This will happen when the first user loads the project. After that the command does nothing (because the folder now exists.)

Feature - Bug Fix: Offline Status Reported Immediately

Previously the Grapple Launcher tried to do an http call to download the main Grapple application stack. If the user was not on the LAN the typical long hang up that Apple delivers for any connectivity failures to resolve before releasing the CPU (as long as 3 minutes) was a nuisance. In LiveCode 4.5.1 DNS calls are now non-blocking so we first ping for the hostNameToAddress of the server. If we don't get anything, this is reported immediately as "You do not appear to be online, or the server is down." If DNS resolves (we get an IP in the result) we assume we have connectivity and proceed to fetch the main app stack.

November 28, 2010: Note this model of fetch the main stack has been abandoned. The main stack is deployed with the launcher in the app bundle. This way a publisher is not dependent on a web service. That said, it was much easier to deliver upgrades using the "cloud" method (load from the net) because you only had to upgrade the single instance on the server and everyone would get it automatically. If I were to get back into "dynamic development" I will revert to this. Or set the launch stack to transparent fetch a new version and replace the one in the bundle without even informing the user.

Bug Fix: Add New File put file at Version Control Root instead of in Project Folder

This was hard to reproduce so we simply added a fail safe routine which checks the global

gServerProjectPath

for a proper project path and if none is found the user is prompted to choose a projects from the projects list. We are not sure how this is happening, but it may be when a brand new user starts up and before has added a file and his preferences do not yet have a project logged in as his last project. At any rate keep an eye out on this one. The symptom will be: a user adds a new file but it does not appear in the project list. But if you look inside the main Versions Control folder, it has been added at the root or top level of Version Control and not the project folder itself. If this happens, simply move the file into it proper Project folder.

_________________________

September 2010:

Connectivity status and user interaction control:

------- Advanced Features Wish List Requires talking to InDesign's API or using Apple Script

Pending "critical mass" need and if really needed, R & D

-- Can we query InDesign with apple script and get a list of links for the document? If so we can scan the links folder and determine if all linked files are present and not on being linked from the client (From AR's wish list:)

__________________________

Deprecated or Not Implemented:

-- Check mod date on local checked files and inform user: highlight the file in the list.