Updated Jul 22, 2008 by ian.charnas
Labels:	Phase-Deploy, Featured

GettingStarted

A quick guide to getting started with Checkpoint

Getting Started

Introduction

Checkpoint watches all the files in a directory (recursively), and allows you to revert your directory to any point in the past that you did a 'commit' to save your changes.

Checkpoint comes as both a command-line utility AND a programming API.

Users will love the Checkpoint command-line utility for its simplicity, and Developers will love to integrate Checkpoint into their Content Management Systems and other software for easy file versioning support.

Installation

Checkpoint requires python 2.5 or later, but other than that it was specifically written to not have any other dependencies.

To install Checkpoint, run:

    $ easy_install checkpoint

Or download the source distribution and run:

    $ python ./setup.py install

Usage

The checkpoint command line utility is so easy to use, even an untrained squash plant could get the hang of it. Let's say you have a directory where you keep your treasured family heirloom word documents. All you have to do is tell Checkpoint to watch that directory for changes:

    $ checkpoint watch /home/charnas/heirlooms

If you're already in the heirlooms directory, all you need is:

    $ checkpoint watch

    Initializing repository for directory: '/home/charnas/heirlooms'
    Committing changes for directory '/home/charnas/heirlooms'
    A	/home/charnas/heirlooms/babys-first-word-document.doc
    A	/home/charnas/heirlooms/letter-to-my-people.doc
    A	/home/charnas/heirlooms/poetry/dan.doc
    A	/home/charnas/heirlooms/poetry/susie-mckee.doc
    New changeset: 1

That's it! Now if you make changes to those word documents, or add or delete things from the directory, or move things around, or whatever, you can commit the changes to the repository like so:

    $ cd heirlooms
    $ rm letter-to-my-people.doc # example file modification
    $ checkpoint commit

    Committing changes for directory '/home/charnas/heirlooms'
    D	/home/charnas/heirlooms/letter-to-my-people.doc
    New changeset: 2

So then you realize you've made a terrible mistake and you didn't mean to delete that file you just deleted in the example. Just tell checkpoint to go back to the desired changeset like so:

    $ checkpoint revert -c 1

    Reverting directory '/home/charnas/heirlooms' to changeset 1
    A	/home/charnas/heirlooms/letter-to-my-people.doc
    New changeset: 3

Phew! What a relief, eh? Doing a checkpoint revert without a specified changeset will undo all changes since the last commit.

What else?

checkpoint status will show you what has changed since the last commit.

checkpoint forget will remove the saved history of changes and eliminate all evidence of the checkpoint repository.

checkpoint recover will attempt to repair missing files after a crash or program interrupt.

You can tell checkpoint to ignore certain paths such as temporary files using the CHECKPOINT_IGNORED_PATTERNS environment variable, which is a colon-delimited list of paths to ignore (wildcards are supported!). For example here's how you would tell Checkpoint to ignore those damned .DS_Store directories on your mac, and also temporary files produced by the vim text editor:

    $ export CHECKPOINT_IGNORED_PATTERNS=".DS_Store:*.tmp"

If something is going totally haywire, putting checkpoint into debug mode using the CHECKPOINT_DEBUG environment variable may help you determine the trouble:

    $ export CHECKPOINT_DEBUG=1

If you want your repositories named something other than .cpt, you will probably be able to guess what the CHECKPOINT_REPOSITORY_BASENAME environment variable will do:

    $ export CHECKPOINT_REPOSITORY_BASENAME=".repository"

Details

Checkpoint creates a sub-directory called .cpt where it stores file revisions and other information. Files are stored as regular flat files. In the future, compression support may be added to Checkpoint to save on disk space.

Checkpoint remembers files by their path and SHA-1 checksum, in order to track file movement and avoid unnecessary duplicates in the repository.

Files that were renamed will be detected as one file being deleted and another file being added. Due to concurrency problems there is no way around this. svn mv does the same thing, try it!

Concurrency is NOT supported. Checkpoint locks the repository using a simple file lock during all commands, so no other process using the checkpoint API will be able to run repository commands until the first process finishes.

When Checkpoint "reverts" to a previous changeset, a new changeset is is created and changes are applied to that changeset until it is equivalent to the desired changeset. This is a deliberate design decision, and while it wastes some space in the database, it doesn't create unnecessary duplicates of backup files, and more importantly it keeps the implementation simple and easy to understand.