SiVeCo -- Simple Version Control

There are lots of powerful SCMs, so why another one? Well, simply because they are too powerful and expensive to install (take lots of disk space, need a database and libraries you currently don't have installed), use (need to find a good GUI to access the repository, ...) and administrate (configuration of the database, ...). One has to do lots of things for features possibly never needed.

SiVeCo is only some things more than the poor man's method of copying a project to another place -- but it makes doing this job really easy, has no dependencies (except standard tools you have installed anyway) and can't be easier to use. There are benefits you really should consider.

1 What it can't do

It is meant to be easy to install and use for someone working alone on smaller projects, with contributors sending patches not too often. So don't use for a 1000-file distributed project with several people working on it.

2 Features

• Easy to install and use
• Small size
• No dependencies
• Normal filesystem interface to the repository
• Every saved version is a fully working copy of your project without wasting disk space
• Changelog handling, execution of scripts before/after creating new versions and other useful things like that.
• Can be converted to other SCMs. Included is an example for mercurial (hg) which can be easily adapted to others which provide a command line interface (subversion, ...).

3 How it works

• You have a working directory in which your project is stored.
• Additionally there is a repository-directory where you save different versions of your project.
• Somewhere you create a tiny config-file for this project, which basically states where those directories are and which files and directories not to save (given by regular expressions).
• Using two simple commands you can save the current state of your project as a new version (command create) or get a certain version back to your working directory (command get) or any other directory.

That's it! How could it be easier?

4 Details, benefits

When you create a new version, your project is not simply copied. When creating a new version, files, which are exactly like in the previous version, are not copied, but created as symbolic links. So you save some disk space while all versions in the repository are fully working copies! You don't need a special tool to explore your repository, use your favourite file manager. Use xxdiff or some other (visual) diff to compare different versions, do whatever you are used to.

So symbolic links are used to save disk space. But you can safely use symbolic links in your projects, too. With every new version a file is created in the repository which helps SiVeCo to recover unchanged files and symbolic links in your original project without mixing things up. There is no need to worry -- what you get back from the repository is exactly what you saved to it.

Symbolic links pointing to a target inside the repository are relative, those pointing to targets outside of the repository are absolute, so you can move the repository around without breaking links.

The additional file (xml) mentioned before does also hold information about when you saved this version, and, if you like, a list of which files have changed, are new and so on. There is place to add a label, version information, changelog, whatever you want. As it is xml, you have the power to use it as needed.

5 Invocation

siveco command configfile [options]

5.1 Create new version

siveco c configfile [-n number] [-d directory] [-l label]

If number is not given, the current version is used as reference. This option is useful if you branch from an older version than the current. There is no need to care about it if you provide a place for tracking information in the config file.
Using directory you can override the working directory stated in the config file.
label is set to none by default. This is overridden by the last element of directory (if given). Of course providing a label has the highest priority.

5.2 Get a version

siveco g configfile [-n number] [-d directory]

If number is not given (or -1), the current version is fetched. Using directory you can override the working directory stated in the config file.

5.3 Compare working directory with saved version (show diff)

siveco d configfile [-n number] [-d directory] [-t type]

If number is not given, the version stated by the tracking information or the current version is used as reference.
Using directory you can override the working directory stated in the config file. type is list (default) or exec. When using exec, for each different file the process diff given in the config file is started. You can also use bexec which starts background processes.

5.4 Remove versions from the repository

siveco r configfile -n number
siveco r configfile -n numberStart-numberEnd

Removes as much of the given versions as possible -- files linked from later versions are not removed, therefore your repository stays consistent.

5.5 Get Information

siveco i configfile [-n number] [-t type]

Prints information about the name and/or label of a certain version (if number is not provided, the current version is used). Can be used for automation using shell scripts:

type	prints out
label	label
nameLabel	name-label

or prints out the history of the versions you saved to the repository:

type	prints out
history	Text version. This is the default type.
historyrev	Text version, reversed order
historyhtm	html version
historyhtmrev	html version, reversed order
historyhtmNH	html version without surrounding <html><body></body></html>
historyhtmNHrev	html version without surrounding <html><body></body></html>, reversed order

5.6 Create archive

siveco a configfile [-n number]

If number is not given, the current version is used.

6 Configuration file

The configuration file, let's call it config.xml, may look like this:

  
<siveco
  workingDirectory="/home/jens/projekte/SiVeCo/001/current/"
  repository      ="/home/jens/projekte/SiVeCo/001/repository/"
  name            ="siveco"
  changelog       ="SiVeCo/changelog.htm"       
  tracking        ="SiVeCo/.siveco.xml"
  preCreateCmd    ="SiVeCo/setVersion.sh"
  afterCreateCmd  ="SiVeCo/createChangelog.sh"
  afterGetCmd     ="SiVeCo/setDevelVersion.sh"
  archiveDirectory="/home/jens/projekte/SiVeCo/001/"
  archiveCmd      ="SiVeCo/createArchive.sh"
  diff            ="xxdiff"
  cmp_cmd         ="cmp -s">

  <verbosity>
    <new      stdout="0" file="1" />
    <changed  stdout="0" file="1" />
    <deleted  stdout="0" file="1" />
    <excluded stdout="0" file="1" />
  </verbosity>

  <exclude
     directories=""
     files      =".*~$|^jedfiles\.lst$|^out/os/.*$|^src/wav/.*\.wav$|^src/wav/encode$"
  />
</siveco>  
  

Entries explained:

workingDirectory

The directory in which you work on your project.

repository

The directory in which versions and additional information is kept.

name

The name of your project.

archiveDirectory, archiveCmd

If you create an archive using the command a, the chosen version is put into directory archiveDirectory/name-label/, afterwards archiveCmd is executed. I use it to remove things which should not be distributed, create a changelog, convert documentation and so on and create the source archive at last. Take a look at the script SiVeCo/createArchive.sh in SiVeCo's source archive for an example.
Provide an empty string for archiveCmd if you don't want to execute a command.

changelog

Path relative to workingDirectory where you keep your changelog. Simply write down your changes in this file (html) and SiVeCo will copy it into the descriptive file in the repository when you create a new version. It will clear the changelog file in your workingDirectory afterwards. This changelog is part of the history you can view using the command i.
Provide an empty string if you don't want to use this feature.

tracking

Path relative to workingDirectory where SiVeCo stores on which version your current work is derived. Just use it (if don't want to: provide an empty string) and do not care about the option [-n number] for the command c.

preCreateCmd

A path relative to workingDirectory where a script/program is located which is executed just before a new version is created. The label of the new version to be created is passed as argument to this script.
I use it to write the label into a header-file for the project. Take a look at the script in SiVeCo's source archive for an example.
Provide an empty string for preCreateCmd if you don't want to execute a command.

afterCreateCmd

A path relative to workingDirectory where a script/program is located which is executed just after a new version is created. The repository number of the new version just created is passed as argument to this script.
I use it to automatically recreate the changelog for the project. Take a look at the script in SiVeCo's source archive for an example.
Provide an empty string for afterCreateCmd if you don't want to execute a command.

afterGetCmd

A path relative to workingDirectory where a script/program is located which is executed just after a new version has been fetched from the repository. The repository number of the new version just fetched is passed as argument to this script.
I use it to automatically set a new label for the project. Take a look at the script in SiVeCo's source archive for an example.
Provide an empty string for afterGetCmd if you don't want to execute a command.

diff

The command which is executed as visual diff, I currently use xxdiff.

cmp_cmd

The command used to compare files. There should be no need to change this.

6.1 Verbosity

The section verbosity tells SiVeCo about the additional output you want to see on the screen and in the file which accompanies every version. 0 means you don't want to see this, 1 tells SiVeCo to print it.

6.2 Excludes

The final section, exclude, tells SiVeCo which files and directories not to include in the repository.

Here is a short reminder about regular expressions (see man 7 regex):

| separates various regular expressions of which only one needs to match

atoms:
^ matches the beginning of a line
$ matches the end of a line
\ followed by one of the characters ^.[$()|*+?{\ matches that character taken as an ordinary character
. matches any single character

An atom followed by * matches any number of the atom.

7 Dependencies

If you have linux or something similar (SiVeCo is reported to be usable under Mac OS X), chances are that you can use it.

• A filesystem which supports symbolic links. Therefore SiVeCo can't be used on Windows.
• The standart unix tool cmp to compare files. This surely is already installed on your machine.

8 Where to get it

http://kisocd.sf.net/siveco.htm

9 Compiling, Installing

Simply type make and copy siveco to somewhere in your path, for example /usr/local/bin/.

---

Jens Wilhelm Wulf (j dot w dot wulf at gmx dot net), 17.08.2004.
Updates: 11.08.2007

---