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 123456

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):

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

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:

...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:

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:

...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:

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: if Bones finds any broken symlinks
inside t2-trunk-APRIL, they are assumed to point to folders, and Bones
will create those folders. 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:

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.