FREQUENTLY ASKED QUESTIONS

This is a list of common questions about Revisions. If you are looking for more of a tutorial-style presentation of how to setup and use the app, check out the illustrated help for Revisions Setup and Revisions Basics. If you don't find an answer to your question, email me at support@revisionsapp.com or mention @RevisionsMacApp in a tweet.

Features

Revisions lets you select any folder in your Dropbox (including deleted folders) and displays a list of all file edits in that folder (including any subfolders) in reverse chronological order. File edits which occurred within a specified interval are grouped together, and the user can manually adjust the grouping. Any edit can be inspected by opening and comparing the pre-edit and post-edit versions of the file or, for supported file types, showing the exact set of modifications using third-party file comparison (diff) apps such as Kaleidoscope, Araxis Merge, Changes, TextWrangler, or BBEdit. This is useful to track what files you have worked on, or what changes a colleague has made in a shared folder.

Revisions is also useful for recovering from unintended file deletions and modifications: It is very easy to download or restore any version of any single file, and, more importantly, it also lets you download or restore an entire folder (or your entire Dropbox) to the state it was in at a particular point in time.

Hey, that's not a question! Yes, the Dropbox web interface has a useful Events page which gives a timeline of edits. However, it does not allow you to select an arbitrary folder to inspect, nor does it let you easily compare two versions of a file to see what was changed. Revisions provides a much more powerful way to inspect file edits in your Dropbox.

Yes, the web interface allows you to undelete files and go back to earlier versions. But restoring old versions of files can only be done one file at a time. If you need to mass-revert a large set of files to some earlier point in time, you are out of luck. The Dropbox support team may be able to help you out, but such help is not immediate and if you have a free account you may not be their highest priority. Revisions allows you to restore a large number of files easily, and you can iterate quickly if needed to find the files at the exact state that you are looking for.

Revisions relies on the fact that Dropbox stores old versions of your files. This is completely transparent to the user: The old versions are stored solely on the Dropbox servers so they do not take up precious disk space on your devices nor are the old versions counted towards your Dropbox quota.

For all accounts (including all free accounts) Dropbox stores a minimum of 30 days of history. This means that with Revisions you are always able to inspect the details of all file edits in your Dropbox going back 30 days from today. You can view the changes retroactively, so if you install Revisions today you will be able to see the last 30 days of activity. If necessary, you can restore any folder (or even your entire Dropbox) to the state it was in at any point in time inside this 30 day period.

Dropbox Plus users who have chosen to purchase the optional Extended Version History feature have access to one year of history. Dropbox for Business users typically have 120 days of history. In some cases (for instance with the legacy Packrat feature) users may even have unlimited history.

Privacy

Revisions is a Mac app that stores all its local data on your computer only, and communicates directly with Dropbox servers for access to your files and file metadata. No external servers have any access to your files or file metadata.

Specifically, old versions of files and file metadata are stored by Dropbox on their servers and is accessed by Revisions over an encrypted connection (https) using the Dropbox API. Revisions stores downloaded file metadata on your computer, inside its app container.

If the user opts in to allow the app to send anonymous usage data, the app will on occasion transmit anonymous data to the developer (revisionsapp.com). Such data includes data on errors encountered and various aggregate statistics, but is designed not to contain any sensitive information (no file data nor file metadata such as filenames) nor any personally identifiable information (such as email addresses).

No. Revisions connects to Dropbox using OAuth, a mechanism by which you (the user) can grant access to your Dropbox files to an app without disclosing your password.

When you click "Connect to Dropbox" in the app, your default browser will open and allow you to sign into Dropbox. You can then grant access to Revisions using the Dropbox website, giving Revisions an access token to access your account. At any time, if you wish to, you can revoke access to the app via the Dropbox website, which invalidates the access token. Your password stays with you and is never passed to the app.

Usage

When Revisions first connects to your Dropbox account, it needs to create a list of all file edits. This is accomplished by asking for revision metadata for each and every one of your Dropbox files. The main factor that determines the indexing time is thus the number of files in your Dropbox. If your Dropbox contains many tens of thousands of files (or more) indexing can take several hours even with an excellent internet connection. (You can see the index progress bars at the bottom-left of the Revisions window.) Fortunately, you can let Revisions do its indexing in the background while you focus on other work, or you can let it index while you take a nap, go to a football game, watch a movie, or whatever else you like doing! :) You can even use Revisions while it is indexing: For instance, you can navigate your Dropbox and restore or download old versions of single files. Some operations howevever (such as downloading or restoring an entire folder) requires that indexing is complete. If you need to, you can quit the app and restart it as you please, and indexing will proceed from where it left off.

Finally, note that during the very early phase of indexing the time estimate can fluctuate significantly. Wait until the time estimate stabilizes to get a decent guess for how long the indexing will actually take. Also note that as Revisions discovers deleted folders during the indexing phase the indexing time may increase from the initial estimate.

No. Revisions version 1.2 and later has no need for automatic re-indexing when the app launches. Thus, feel free to quit and restart as often (or as seldom) as you like!

See however the following question "Is Revisions guaranteed to detect all file changes?" for a related issue.

On initial launch, Revisions indexes the version history of each and every file in your Dropbox, so all recent edits are guaranteed to be detected.

While running, Revisions receives updates of all editing activity in real time, and is guaranteed to detect all file changes.

On each launch after the initial indexing, Revisions detects changes using the /delta endpoint of the Dropbox API. By design, this mechanism is guaranteed to detect changes that leave your Dropbox in an altered state, but Dropbox does not guarantee that this mechanism detects compound changes that leave your Dropbox unaltered (the most common such case would be the addition of a file and its subsequent deletion, all while Revisions was not running). Many such edits are indeed detected using the current mechanism, but it is not fully guaranteed.

One of the signature features of Revisions is that you can obtain a copy of an entire directory (including any subdirectories) at the state it was in at a user-specified point in time. To do this, first select the folder you are interested in using the folder selector at the top. Make sure that Revisions has finished indexing all files in your Dropbox. Then, move the pointer over the small space between any pair of adjacent edit groups, and click on one of the folder action buttons that appears, to download or restore a folder to that particular point in time.

First, note that there are two sets of filters: (a) The filters used when displaying files in the activity view, and (b) the filters used when indexing files (when interacting with the Dropbox servers).

In most cases, you'll want to only set display filters, leaving the index filters empty. This is because any changes to the display filters take effect immediately so it is easy to iterate to find the exact conditions that filters out all files you want to ignore and nothing else. In addition, in case you choose to download or restore an entire directory, in most cases it is important that hidden (ignored) files are also restored to their appropriate state, in particular if there are linkages between the ignored and the not-ignored files.

If however you have certain directories with a very large number of files (or files that change very often) and you wish that such directories not be indexed at all by Revisions, you could choose to edit the index filters. If you do, it is recommended that you re-index from scratch after updating the filters, as otherwise files that ought to be ignored may already be previously indexed and visible. The filter setup interface provides a button to re-launch and re-index, activated upon any changes to the index filters.

Most users will probably find the standard filter conditions ("begins with", "ends with", "contains", "matches") sufficient. The string you enter is directly compared to the filename (note: in a case-insensitive way!) to check for the match. You can choose whether to match only the file or folder name, or the entire Dropbox path, which take the form:

/somefile.pdf

/somefolder

/somefolder/anotherfile.txt

/somefolder/anotherfolder

/somefolder/anotherfolder/deepfile.jpg

If you need to use more complicated matching, you can use regular expressions. This is an advanced topic. The main special characters that you'd be likely to use are:

- The forward slash / is a reserved character in a regular expression, so to literally match it put the "escape" character backslash \ in front of it

- The period . is also a reserved character (matching any character), so to literally match it put a backslash directly in front of it

- The caret ^ only matches the beginning of the name or path. This can be used to make sure that only top-level files or folders match

- The dollar $ only matches the end of the name or path.

- Parentheses () are used to group subpatterns together, and the vertical bar | is used to indicate that one subpattern or another is allowed

Viewing and comparing files

When you click the "view" button corresponding to a given version of a file, Revisions downloads the file and then opens it using the system default app for that particular file type. If you want to change the default app, first click the "download" button corresponding to this file, save the file wherever you wish, then switch to the Finder, select the file, and choose "Get info..." from the File menu. Under "Open with:", select your preferred app and click the "Change all..." button.

When a file has been modified in a given edit group it is possible to compare the version of the file as it existed prior to the edits with the version produced by those modifications. Clicking on the "compare" button opens both versions and lets you manually scan for the differences between them. For certain types of files, however, there exist third-party apps that can compare (diff) the versions and display exactly what was changed: Revisions currently natively integrates with Kaleidoscope, Araxis Merge, Changes, TextWrangler, and BBEdit (and others are available via scripting, see the next question!). Each of these can display diffs of plain-text files (and related files that are essentially plain-text with markup). In addition, Araxis Merge and Kaleidoscope can display diffs of various types of image files. If you are not familiar with any of these we recommend that you try out Kaleidoscope, an excellent app which has a 15-day free trial period.

To use any one of these external diff apps with Revisions, first download and install your preferred app, and launch it at least once initially to make sure it is working properly. Then in the setup tab of Revisions, select that app from the drop-down menu. Finally, clicking on the "compare" button will open the comparison in the selected diff app for those file formats supported by the app. If for some reason a file that you think ought to open in the diff app does not (i.e. if it instead is compared by separately opening the pre-edit and post-edit versions) then contact me... I should be able to help you out!

If you'd prefer to use another file comparison app than one of the natively supported ones (for instance Apple's own FileMerge app), you can do this via the "Custom script" option available in Revisions 1.2.1 and later.

(This is an advanced option. If you want to get it working but have trouble following the instructions, email me and I'll be glad to help you out!)

Briefly, you'll need to put a plain-text file called "diff.scpt" (without the quotes) into the "Library/Application Scripts/com.bayesbits.Revisions" folder. (If these folders do not exist, run Revisions 1.2.1 or later at least once and it will auto-generate them.) The file should contain an AppleScript script that should read the following two files

"/Users/username/Library/Containers/com.bayesbits.Revisions/Data/diffs/pathA"
"/Users/username/Library/Containers/com.bayesbits.Revisions/Data/diffs/pathB"

from which it gets the full paths of the files to be diffed, and then launch the diff. Note that "username" should be replaced by your username. It is also a good idea to validate the paths before launching the diff program. Example scripts for launching FileMerge and DeltaWalker are available in the latest direct-download disk image (these scripts also work with the Mac App Store downloaded app). Below is a sample script for launching FileMerge (remember to edit the username if using this script!):

Backups and version control

Not really. Together, Revisions and Dropbox (in particular for accounts with unlimited history) provide a useful setup that backs up a lot of your data. (If you currently have no effective backup of your important documents, this setup will be a huge improvement!) However, most users will want features and protections that this simple setup cannot provide. While a full discussion of backup is out of the scope of this FAQ, here are some pros and cons of using Revisions and Dropbox for backing up your files:

Pros:

Easy setup. If you are reading this, you are probably already using Dropbox.

Offsite. Can your files survive a fire or burglary to your home or office? While local backups are great, it's nevertheless important to keep at least one set of backups in a separate physical location from the devices being backed up.

Access from anywhere. Need that old version of a file while on the road? This is super-easy with Dropbox and Revisions.

Cons:

Network access required. Dropbox only updates your files (and thus accumulates old versions) while you are online. If you frequently work without internet connectivity and need to backup files while offline you will need to look at other solutions. Obviously, if you have a slow internet connection but you work with very large files (such as digital video), the situation is similar.

Dropbox folder only. While many users already store all the documents they are working on in their Dropbox folder, this does not include system files, apps, preference files, etc. If you need to be able to quickly setup a new machine with a stored copy of your particular work environment then you'll need software which backs up your entire drive as opposed to just your documents.

Finally, some limitations exist in how Dropbox stores old versions of your files. See the section "Limitations" on this page for a list of various problematic issues that may or may not apply to your case.

In almost all cases, if you are familiar with and comfortable working with dedicated version control systems such as subversion or git, there is absolutely no reason to switch. Such systems contain many features which are absent from Revisions, such as branching and merging, as well as manual commits and updates. Indeed, such dedicated version control is absolutely critical for many projects.

Instead, Revisions is targeted towards users who may have never heard of version control software, but who would nevertheless benefit greatly from at least a rudimentary form of version control in their work. There are countless teams, jointly working on a shared set of files via Dropbox shared folders, using email or other separate channels for notifying their colleagues of what files have been changed and what the exact changes were. This type of information can be easily seen from an edit timeline and using diff programs. In many such cases, setting up a dedicated version control system (and having everyone on the team learn how to properly use it) may not be appropriate. Revisions can be immensely useful in this type of settings as a form of "informal version control" that let's everyone see what edits have been made, without having to learn (and use) formal version control.

Similarly, many users who use git or subversion for some of their projects do not (for whatever reason) use it for all of their files. Such users may want to use Revisions as a form of light-weight version control for those files that are not part of a formal version control system.

Price

Revisions is now (from version 2.3 and up) completely free of charge. Note that to access some of the features the app requests that you share your experience of the app. (Earlier versions of the app used a freemium model where some features were only available via a purchase.)

I support all users of the app, but priority is given to users who supported the app by purchasing Premium prior to the release of version 2.3.

Limitations

You need an Apple Mac computer running OS X 10.9 or higher. You also need a Dropbox account (free or paid).

Memory, disk space, and processing power:

If you have a very large number of files (tens of thousands or more) in your Dropbox, be prepared that the index created by Revisions can be quite big, on the order of one gigabyte or more. In such cases please make sure that you have sufficient disk space available. The index is stored on your local drive (in the app container allocated to sandboxed apps) and it does not consume your Dropbox quota.

While the app should run on an old Mac (assuming it runs OS X 10.9 or higher), the user interface may unfortunately be sluggish if the machine is very old. It is recommended to run the app on a relatively modern (roughly 2012 or later) Mac.

The interface (API) Dropbox provides to third parties sets a couple of limits that may in some cases be restrictive and prove problematic for Revisions:

The maximum number of files and folders in a folder is 25,000. Note that this limit does not count any files in subfolders, so it is fine to have a directory tree with a very large total number of files, as long as there are not too many files or folders in the same directory listing. While most users will probably not hit this limit, if you have a particularly large photo or music collection, or use your Dropbox in some specialized way, this may become an issue, depending on the details of how the files are stored. Revisions will let you know if you are over this limit, in which case not all files may be shown and folder operations involving these folders may not work as planned.

Also note that the maximum number of old versions of a file is 1,000. This should be enough for typical Dropbox use, but if you for instance have a file in your Dropbox that is periodically automatically updated by your system you may easily hit the limit.

Yes, but it is important to note that both Dropbox and the default Mac OS X filesystem are case-insenstive but case-preserving. Thus you cannot have separate files which differ only in the case of their filenames. For instance "file.txt" and "File.txt" and "FILE.txt" all refer to the same file. The case-preserving property means that if you created the file with the name "File.txt" then Mac OS X and Dropbox will store the case and present it to you in this exact form. However, if you subsequently upload a file called "file.txt" to Dropbox it will overwrite the old file "File.txt" and effectively become a new version of this file.

Yes, unfortunately. Below are the ones we are aware of:

1. Dropbox does not currently do a good job if a file with a given name is deleted and replaced by a folder by the same name (all inside the same parent directory). In this case, the currently existing folder "masks" the earlier identically-named file, so Revisions (and also the Dropbox web interface) does not see that there previously existed a file at this location. A completely analogous problem exists if a folder is deleted and replaced by a file with an identical name.

While in most cases the above problem would not seem to occur too frequently, there are some situations in which this can be problematic. In particular, some Mac applications store their documents as packages (directories of files) rather than individual files. While OS X displays these packages as files to the user, they are stored on Dropbox as the folders they really are. This in itself is not a big problem, but if an app switches from using a file to using a package, or vice versa, this makes previous versions of the document inaccessible on Dropbox. Apple's productivity apps Keynote, Pages, and Numbers have at some point all used this type of a package format for documents, and there have also existed options to save as a flat file instead of a package. Thus, until this problem of files and folders masking each other has been fixed in Dropbox, beware.

2. Similarly, a shared folder may mask the version history of a standard Dropbox folder. When you share a (previously private) folder, the present version of all existing files are 'copied' to the new shared folder (which has the same name as the original private folder). The person you shared with does not have access to the version history of the folder prior to sharing. Unfortunately, this also means that you yourself do not have access to the prior version history after sharing. The version history is not completely forgotten however, because the moment you unshare the folder, you can obtain access to old version history again. If keeping the version history visible is important, my recommendation is to rename the old folder before sharing it.

3. Another issue is that while files are fully versioned, folders are not. This means that it is not always possible to distinguish between empty folders and non-existent folders when restoring old versions of directory hierarchies.

4. Files and folders, in the standard OS X filesystem, come with metadata. Each file has an owner and belongs to a group, and files have permissions that govern who can read, modify, or execute the file (for programs). In addition, file metadata contain information on when the file was created and when it was last modified. Not all of this metadata is stored on Dropbox, so it cannot be guaranteed that it is faithfully restored.

5. I also need to point out here that all file versioning on Dropbox is simply based on the full file path (filename and ancestor folder names). Thus, if you move or rename a file, it will show up in Dropbox as if the old file was deleted and a new file was created, and any old versions of the file stay put at the old file path, while the new file has an empty history.

Distribution

The Mac App Store provides a convenient way for users to find, install, and update apps. I want to provide the best possible experience for my users, so distributing through the store is important for me.

Nevertheless, there are situations in which it is useful for users to have direct downloads available as well. In particular, if you (for whatever reason) need to install a version of the app other than the most recent version, this is not possible in the app store. From the website you may download any released version of the app. Another benefit of direct downloads is that updates and bug fixes can be released immediately on our website, while the Mac App Store review process may take up to a week (or more) to approve even relatively minor updates to the app. I aim to release bug fixes as soon as I can, so this is an important issue for me.

I strive to keep the Mac App Store app and the direct download app, as far as possible, in sync. Thus, in most cases there will not be any significant differences between identically-numbered versions of the app. The website may at times contain more recent versions of the app, either as part of a public beta release or simply because the latest stable release is still under review before it appears on the app store.

Getting in touch

Revisions was conceived and is developed by Patrik Hoyer in Helsinki, Finland.

Email me at contact@revisionsapp.com or just mention @RevisionsMacApp in your tweet.

I am very sorry to hear that, in some way or another, my app is misbehaving. Just contact me (email contact@revisionsapp.com or tweet @RevisionsMacApp) and explain the problem you are having. Try to be specific: Avoid saying that some feature "does not work", instead explain exactly what happened (and why that was not what you expected). The best descriptions take the form "I did A, and expected B to happen, but instead C happened". Detailed descriptions make it possible for me to give helpful responses and if necessary fix the problem for you.

I strive to produce software of the highest quality. Hence, if you do find a bug, please do let me know so that we can fix it as soon as possible (both for you and for any other user who may be experiencing the issue). If you wish, I can notify you when the bug is fixed and an updated version of the software is ready for download. See the answer to the previous question on how to describe the bug you are observing.

I'd be happy to receive any comments by email, but if you use and enjoy the software it would be great if you could write a review on the Mac App Store, or tweet about it, or share it using Facebook. Of course, feel free to criticize as well, though I'd be really grateful if you gave me a chance to help you out first, if you are having any problems with the app! In any case, I'm looking forward to hearing from you!