gitty.pl -- Single-file GIT like version system

This library provides a first implementation of a lightweight versioned file store with dynamic meta-data. The store is partly modelled after GIT. Like GIT, it uses a content-based store. In fact, the stored objects are compatible with GIT. Unlike GIT though, there are no trees. Each entry (file) has its own history. Each commit is associated with a dict that can carry aribitrary meta-data. The following fields are reserved for gitties bookkeeping:

name:Name

Name of the entry (file)

time:TimeStamp

Float representing when the object was added to the store

data:Hash

Object hash of the contents

previous:Hash

Hash of the previous commit.

The key commit is reserved and returned as part of the meta-data of the newly created (gitty_create/5) or updated object (gitty_update/5).

 gitty_open(+Store, +Options) is det

Open a gitty store according to Options. Defined options are:

driver(+Driver)

Backend driver to use. One of files or bdb. When omitted and the store exists, the current store is examined. If the store does not exist, the default is files.

 gitty_driver(+Store, -Driver)

Get the current gitty driver

 gitty_close(+Store) is det

Close access to the Store.

 gitty_file(+Store, ?Head, ?Hash) is nondet

 gitty_file(+Store, ?Head, ?Ext, ?Hash) is nondet

True when Hash is an entry in the gitty Store and Head is the HEAD revision.

 gitty_create(+Store, +Name, +Data, +Meta, -Commit) is det

Create a new object Name from Data and meta information.

Arguments:

Commit

- is a dit describing the new Commit

 gitty_update(+Store, +Name, +Data, +Meta, -Commit) is det

Update document Name using Data and the given meta information

 filter_identity(+Meta0, -Meta)[private]

Remove identification information from the previous commit.

To be done

- : the identity properties should not be hardcoded here.

 gitty_update_head(+Store, +Name, +OldCommit, +NewCommit) is det[private]

Update the head of a gitty store for Name. OldCommit is the current head and NewCommit is the new head. If Name is created, and thus there is no head, OldCommit must be -.

This operation can fail because another writer has updated the head. This can both be in-process or another process.

Errors

- gitty(file_exists(Name) if the file already exists

- gitty(not_at_head(Name, OldCommit) if the head was moved by someone else.

 gitty_data(+Store, +NameOrHash, -Data, -Meta) is semidet

Get the data in object Name and its meta-data

 gitty_commit(+Store, +NameOrHash, -Meta) is semidet

True if Meta holds the commit data of NameOrHash. A key commit is added to the meta-data to specify the commit hash.

 gitty_history(+Store, +NameOrHash, -History, +Options) is det

History is a dict holding a key history with a list of dicts representating the history of Name in Store. The toplevel dict also contains skipped, indicating the number of skipped items from the HEAD. Options:

depth(+Depth)

Number of entries in the history. If not present, defaults to 5.

includes(+HASH)

Ensure Hash is included in the history. This means that the history includes the entry with HASH an (depth+1)//2 entries after the requested HASH.

 read_history_to_hash(+Store, +Start, +Upto, -History)[private]

Read the history upto, but NOT including Upto.

 save_object(+Store, +Data:string, +Type, -Hash) is det[private]

Save an object in a git compatible way. Data provides the data as a string.

See also

- http://www.gitguys.com/topics/what-is-the-format-of-a-git-blob/

bug

- We currently delete objects if the head cannot be moved. This can lead to a race condition. We need to leave that to GC.

 gitty_fsck(+Store) is det

Check the integrity of store.

 fsck_object(+Store, +Hash) is semidet

Test the integrity of object Hash in Store.

 load_object(+Store, +Hash, -Data) is det[private]

 load_object(+Store, +Hash, -Data, -Type, -Size) is det[private]

Load the given object.

 gitty_save(+Store, +Data, +Type, -Hash) is det

 gitty_load(+Store, +Hash, -Data, -Type) is det

Low level objects store. These predicate allows for using the store as an arbitrary content store.

Arguments:

Data	- is a string
Type	- is an atom denoting the object type.

 gitty_hash(+Store, ?Hash) is nondet

True when Hash is an object in the store.

 delete_object(+Store, +Hash)

Delete an existing object

 gitty_reserved_meta(?Key) is nondet

True when Key is a gitty reserved key for the commit meta-data

 is_gitty_hash(@Term) is semidet

True if Term is a possible gitty (SHA1) hash

 delete_head(+Store, +Head) is det

Delete Head from the administration. Used if the head is inconsistent.

 set_head(+Store, +File, +Head) is det

Register Head as the Head hash for File, removing possible old head.

 gitty_diff(+Store, ?Hash1, +FileOrHash2OrData, -Dict) is det

True if Dict representeds the changes in Hash1 to FileOrHash2. If Hash1 is unbound, it is unified with the previous of FileOrHash2. Returns _{initial:true} if Hash1 is unbound and FileOrHash2 is the initial commit. Dict contains:

from:Meta1

to:Meta2

Meta-data for the two diffed versions

data:UDiff

String holding unified diff representation of changes to the data. Only present of data has changed

tags:_206150{added:AddedTags, deleted:DeletedTags}

If tags have changed, the added and deleted ones.

Arguments:

FileOrHash2OrData

- is a file name, hash or a term data(String) to compare a given string with a gitty version.

 udiff_string(+Data1, +Data2, -UDIFF) is det[private]

Produce a unified difference between two strings. Note that we can avoid one temporary file using diff's - arg and the second by passing =/dev/fd/NNN= on Linux systems. See http://stackoverflow.com/questions/3800202

 data_diff(+Data1, +Data2, -UDiff) is det

Diff two data strings line-by-line. UDiff is a list of terms of the form below, where L1 and L2 provide the starting line in Data1 and Data2 and S1 and S2 provide the number of affected lines.

udiff(L1,S1,L2,S2,Diff)

Diff is a list holding

+ Line

Line was added to Data1 to get Data2

- Line

Line was deleted from Data1 to get Data2

Line1 - Line2

Line was replaced

=(Line)

Line is identical (context line).

 make_diff(+List1, +List2, +Lcs, +Context0, +Line1, +Line2, -Diff)[private]

 join_diff(+Diff, -UDiff) is det[private]

 udiff_string(+UDiff, -String) is det

True when String is the string representation of UDiff.

 list_lcs(+List1, +List2, -Lcs) is det[private]

To be done

- Too slow. See http://wordaligned.org/articles/longest-common-subsequence

Re-exported predicates

The following predicates are exported from this file while their implementation is defined in imported modules or non-module files loaded by this module.

 gitty_file(+Store, ?Head, ?Hash) is nondet

 gitty_file(+Store, ?Head, ?Ext, ?Hash) is nondet

True when Hash is an entry in the gitty Store and Head is the HEAD revision.

 gitty_save(+Store, +Data, +Type, -Hash) is det

 gitty_load(+Store, +Hash, -Data, -Type) is det

Low level objects store. These predicate allows for using the store as an arbitrary content store.

Arguments:

Data	- is a string
Type	- is an atom denoting the object type.