Bones: version control

Page partially updated March 22, 2010

Preamble

Bones is a project version control management system, though that is very much of an overstatement -- Bones is really basic!

Bones came about because the version control systems out there, such as GIT, SVN and Fossil, have limitations and/or are very complicated and big. I did setup Fossil for my Woof project, but ran into five limitations, the fifth being lack of support for symlinks and that was the last straw. I wrote about the Fossil saga on my blog 1 2 3 4 5 6

There's a project called Dim which is promising but is a work-in-progress.

So, I thought why not knock up something that will do the job for me? I have named it Bones and have implemented the core functionality.

Considering the limitations that I had encountered in other version control systems, I have designed Bones differently: Bones is "project-centric" rather than "file-centric". That is, Bones archives the entire project rather than individual files. I also wanted extreme easy of use.

The easiest way to explain is to run through how to set up Bones for my Woof project, in these simple steps...

Getting started

Bones is just a shell script named 'bones', plus one or more small support scripts (currently have 'bones_diff.pl' created by ecube). Usage involves executing 'bones' with some parameter, and in some cases a GUI pops up when Bones needs extra information.

If you have a recent distro built from Woof, such as my Quirky, then you will already have the 'bones' script. If you don't have it in your Puppy, or want to check if you have the latest, get it from here:
Quirky PET repository
...just download then click on it to install. If using a non-Puppy distro, 'tar -zxf bones-xxx.pet' will expand it and then manually install.

To get going, from the user's perspective, is just two steps...

To setup a project is very easy. There is one little formality: your project "working directory" must be named starting with the project name. In the case of Woof, the project name is "woof", so create a directory named like this:

> mkdir woof-tree
> cd woof-tree
> bones setup

...then run 'bones setup'. Choose a username for yourself and enter the URL for downloading the 'woof' project:

setup

In the case of the Woof project, the 'download_url' parameter is:

http://bkhome.org/bones/woof/

The 'bones' script will automatically create a directory ../woof-bones and this is the project "repository" where the complete history of the project will reside.

Step two is to download the project. Just type this:

> bones download

...this will download the project repository and then build all the files in your 'woof-tree' working directory. That's it, you are ready to use Woof.

You don't have to remember what commandline options 'bones' accepts (setup, download, etc.) as there is a main GUI for launching them. Just type 'bones' or 'bones gui' at the shell prompt, and you will get this window:

main-gui

...note though, the very first time that you run 'bones', the setup window will launch, so that things get setup properly for further usage.

Usage: administrator

I have designed Bones for the "benevolent dictator" model, where there is only one boss, who has the username 'administrator'. As the administrator of Woof, I'll explain usage from my perspective...

I have my Woof project, let's say in directory 'woof-tree'. To setup Bones, I need a file '../woof-bones/filelist'. 'filelist' is just a list of what is to be saved. This can be files or directories and wilcdards are allowed. In my case 'filelist' has this in it:

boot
packages-templates
rootfs-skeleton
support
0pre
0setup
1download
2createpackages
3builddistro
create_new_woof
DISTRO_PKGS_SPECS*
PKGS_MANAGEMENT
DISTRO_PET_REPOS
DISTRO_SPECS
README.txt
Packages-puppy*
PKGS_HOMEPAGES
woof_gui
woof_gui_tabs
DISTRO_COMPAT_REPOS*
findwoofinstalledpkgs

I created this file manually, but files or directories can be added by the command:

> bones add <file or directory>

That's all that is needed to set it up. All that I have to do now is:

> bones save

The first time that I save, a tarball is created of the entire project, at '../woof-bones/woof-<date>REFERENCE.tar.gz'.
Every time in the future that I type 'bones save', a delta file gets created of the difference between the latest and previous tarballs. I have only done nine saves so far, and this is what my 'woof-bones' directory looks like:

woof-bones-dir

...from a user perspective, after you have done a 'bones download' the above is almost exactly what you will have in your own 'woof-bones' directory (minus the 'administrator' file).

I will be able to reconstruct any prior save of Woof, simply by starting with 'woof-20091202081304REFERENCE.tar.gz' and applying the deltas until the desired save is reached.

As Bones is not file-centric, to examine the history of an individual file is more difficult. Bones would have to recreate the tarballs of each save and extract the file from each, then a file-history can be created. The downside is that it will take awhile, but I am enploying caching.

Whenever I want to make the latest version of Woof publically available, I just type this:

> bones upload

Usage: user

From the user perspective, just run 'bones download' whenever you want to update to my latest version of Woof.

You will also be able to contribute to development of Woof, if you wish. If you run 'bones save' then a .delta file gets created with your changes and with your username in the file, for example 'woof-20091227122321-20091230345600john.delta'.

I'm currently not thinking in terms of anyone else having upload right to my Woof project, instead, 'john' can email his .delta files to me. So it will be a "circular" contribution pattern rather than the distributed "star" pattern that GIT and others employ.

Future

Bones is simplistic so far, almost trivial, but solves my immediate need to keep a compact history of my project.

It's early days. I need to test basic functionality some more. Future work will be to improve the mechanism for users to contribute to development of Woof, and mechanisms are required to view histories of individual files -- probably with caching.

Further notes

Bones is intended to run on any Puppy Linux or Puppy-derivative, version 4.3 or later. However, Bones will work on another Linux distro if you have these packages installed:

xdelta3
gtkdialog3 (use our version 0.7.20-patriot-e-1 which has bug fixes)
wget
openssh
gftp