Bones: version control

Page updated January 11, 2015

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

EDIT jan. 2015: Fossil has improved since then (2009). For example, now supports symlinks.

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.

EDIT Jan. 2015: That was back in 2009. I got Bones up to version 0.2.2, and used it for my Woof project. Later on I migrated Woof to Fossil. Late 2013, the Puppy Linux community took over Woof, named it woof-CE, and hosted it on a GIT repository.
January 2015, I have improved Bones somewhat, and the version is now 0.3. I have started hosting my projects again with Bones.

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 (but individual files can also be selected). I also wanted extreme easy of use.

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 distro such as my Quirky (a fork of Puppy Linux), 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:
noarch 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.

I will use my own projects as examples in this page. I strongly suggest that you follow my folder naming and directory hierarchy. OK, take the case of my T2 project -- this is my local version of the T2 project found here: http://t2-project.org
My local T2 has many changes compared with the official T2, as I am building specifically for Quirky and Puppy Linux and derivatives. I do attempt to sync with the official T2 sometimes.

In the case of my T2 project, the project name is "t2", so create a directory hierarchy named like this (in a partition with a Linux filesystem, and at least 30GB free), and running as root (administrator):

> mkdir projects
> cd projects
> mkdir t2-project
> cd t2-project
> bones setup

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

setup

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

http://distro.ibiblio.org/quirky/quirky6/project/t2

Do not put anything into the username and password boxes.

The 'bones' script will automatically create a directory ../t2-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 't2-project' working directory. That's it, you are ready to use T2.

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 't2', I'll explain usage from my perspective...

I have my T2 project, in directory 't2-project'. To setup Bones, I need a file '../t2-bones/filelist'. 'filelist' is just a list of what is to be saved, one entry per line. This can be files or directories. In my case 'filelist' has this in it:

t2-trunk-APRIL/architecture
t2-trunk-APRIL/config
t2-trunk-APRIL/doc
t2-trunk-APRIL/download
t2-trunk-APRIL/kernel
t2-trunk-APRIL/misc
t2-trunk-APRIL/package
t2-trunk-APRIL/scripts
t2-trunk-APRIL/source
t2-trunk-APRIL/target
t2-trunk-APRIL/0-README
t2-trunk-APRIL/COPYING
t2-trunk-APRIL/extract-sources
create-t2-tarball
sources-2-alphabetical
check-build-order

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 '../t2-bones/t2-<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 two saves so far, and this is what my 't2-bones' directory looks like:

t2-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 't2-bones' directory (minus the 'administrator' file and LATEST/PREVIOUS tarballs).

Bones is able to reconstruct any prior save of T2, simply by starting with 't2-20150106215851REFERENCE.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 employing caching. This is a work-in-progress.

Whenever I want to make the latest version of T2 publicly 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 T2.

Note, read my blog sometimes, I will announce progress with T2 and when I have uploaded a significant new version. http://bkhome.org/news

This is what my T2 working directory looks like:

t2-project

The .html file is not part of the project, I just put it there for my own convenience. The 't2-book.html' file is the T2 user manual that I downloaded from the T2 website.

After you run 'bones download', you will see those three folders. However, 'download-sources' is not in 'filelist' -- it is where source packages get downloaded to.

A technical detail: 't2-trunk-APRIL/download' is an entry in 'filelist', however it is a broken symlink. Bones just assumes it is supposed to point to a folder, and Bones will create the folder. That is how 'download-sources' got created.
I wanted a folder outside of 'filelist', that would not get wiped when 'bones download' is executed.

Whenever you subsequently run 'bones download', it is only folders and files in 'filelist' that get updated.

Inside 't2-trunk-APRIL', there is a README file with basic instructions on how to use T2, and you can compile a complete system from source -- the binary files can later be used to build a "April series" Puppy or Quirky distro.

User: making changes

When using T2, there is a high likelihood that you will want to make changes inside 't2-trunk-APRIL'. The problem is, when you sync with me by running 'bones download', everything in 'filelist' gets wiped and updated.
There are two solutions to this problem:

1. Save your changes as a .delta file
If you run 'bones save' then a .delta file gets created with your changes and with your username in the file, for example 't2-20091227122321-20091230345600john.delta'.

You can email your .delta file to me, for consideration for inclusion in my "official" T2. No guarantees on that though.

My 'benevolent dictator' model does not allow you to run 'bones upload' to contribute directly to my online T2 repo, it is more of a "circular" contribution structure, rather than a "star" structure as used in other version control systems.

2. Your changes extracted to a separate folder
This happens automatically when you run 'bones download'. Bones will find any changes that you have made since the last 'bones download', and will save all of your changes in a separate folder, named ../t2-user-modified-<date>

For example, 'filelist' contains this entry:

t2-trunk-APRIL/package

...which is actually a directory. So, all of 'package' gets wiped, then replaced with the downloaded new 'package'.

However, anything inside 'package' that you have modified, whether an existing file or new ones added, get saved in ../t2-user-modified-<date>

There is one little precaution to take with this save-mechanism. Bones determines changed or new files by their 'modify date'. If later than the last download, the file is moved to ../t2-user-modified-<date>.
Therefore, if you add any new files, be sure their modify-date is later than last download -- 'touch' them if necessary.

Another awkward thing is that you can't delete an of the official project files. If you do, it will simply be restored on the next 'bones download'.

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 T2 (qualification: for Quirky/Puppy specific development, yes, work on my T2, but generally users are encouraged to contribute directly to the official T2 project at http://t2-project.org), 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
gtkdialog (use version 0.8.x)
wget
openssh
sshpass (needed by administrator only)

PET packages of these can be found here:
x86 PET repository or amd64 PET repository
...if you are running an amd64 (x86_64) distro, look in the latter repo.

Do be sure that you have the latest version of Bones -- see link at top of page.

Disclaimer

Use Bones and T2 at your own risk. I, Barry Kauler, do not accept any responsibility for errant behaviour. Bones and T2 are created and documented in good faith, however you download and use it with understanding of this total disclaimer.

© Copyright Barry Kauler 2009, 2015 bkhome.org All reproduction rights reserved