[$Id: install.txt 57004 2008-08-05 14:52:33Z hpk $]

vadm: versioning of system files and directories 
===================================================

**vadm** is a simple svn-like command line tool for 
versioning unix system files including tracking of 
POSIX ownership and permission information.  
vadm is released under the terms of the GPL Version 3
and was written by Holger Krekel with initial 
contributions from Jens-Uwe Mager. 

.. contents::

Installing VADM 
-----------------

**vadm** depends on the `py lib`_ which provides programmatic access to subversion
by using the 'svn' command line tool.  The **vadm** scripts also will make use 
of the **sudo** command which usually is available on Unix and OSX systems. 

.. _`py lib`: http://pylib.org 
.. _`py lib tarball`: http://codespeak.net/py/dist/download.html#downloading-a-tar-zip-file-and-installing-it

with easy_install 
+++++++++++++++++++

1. `Install easy_install`_ if you don't have it.  On linux distributions the package name you should look for is "setuptools" or "python-setuptools". 
2. type ``easy_install vadm`` (this should install the py lib dependency).

.. _`Install easy_install`: http://peak.telecommunity.com/DevCenter/EasyInstall#installing-easy-install

manually with setup.py 
++++++++++++++++++++++++

1. download the `py lib tarball`_  and install it like this::

     tar zxvf py-0.9.1.tar.gz
     cd py-0.9.1 
     python setup.py install 

2. download the `vadm tarball`_  and install it like this:: 

     tar zxvf vadm-0.6.0.tar.gz
     cd vadm-0.6.0
     python setup.py install 
  

working from development 
++++++++++++++++++++++++++++

If you want to follow the development version you ca type 
something like this::

     svn co https://codespeak.net/svn/vadm/dist/vadm 

and add the ``vadm/bin/`` directory to your ``$PATH`` variable. 
The **vadm** script will automatically use the development version. 


Getting Started 
---------------------

You first need to create a repository for storing 
information about your system files::

    vadm create /path/to/my/sysrepo 

Afterwards you can checkout from the newly created 
repository::

    vadm checkout file:///path/to/my/sysrepo  

Multiple users can checkout from the same repository.  EAch
of the users will have a "working copy" in its ``.vadm/hostwc`` 
directory.  

Note that the vadm script mandates execution as a non-root user
that has the right to execute ``sudo``.

For adding, committing, reverting or inquiring of files 
and directories you may now use svn-like commands, including
their abbreviations.  For example:: 

    vadm add /etc/passwd    # add this file to version-control 
    vadm commit -m "passwords" /etc

    vadm log /etc/passwd    # show list of commits to this file

    vadm status /       # show status of versioned files 
    vadm st             # show status of current dir 
    vadm help           # lists all available commands 

Because **vadm** uses subversion under the hood you can 
install commit notification and other hooks in your repository. 
With ``vadm config`` you can get information about your local 
working copy and the repository url. 

Some background and hints 
---------------------------------------------------

Here are some background notes and hints: 

- if you want to auto-commit nightly you
  may create a crontab entry like this::

    59 23 * * *  /usr/bin/vadm ci -m "autocommit" / >/dev/null


- **vadm** works by mapping all versioned files 
  into a per-user working copy.   Permissions
  and ownership information are kept in 
  ``vadm:posix`` svn properties.  The 
  Working copy is usually kept under 
  ``$USER/.vadm/hostwc``.   You may cd there
  and use ``svn`` for introspection directly. 

- When you issue ``vadm add dir/somefile`` **vadm** 
  creates and adds a directory ``dir`` to the WC,
  copies the `somefile` to the WC and schedules 
  it for addition.  

- For almost any command, vadm will internally 
  first update the working copy files from the corresponding
  filesystem information.  This imposes a startup overhead
  which is usually not noticeable on modern systems if you 
  only deal with text configuration files. 

- You can always remove the Working Copy in
  ``$USER/.vadm`` and/or directly perform ``vadm checkout URL``
  which will always remove the working copy before
  re-creating it.  **vadm** can re-create all its information from the 
  repository and the life filesystem.  However, 
  any information that only exists in the working
  copy (like files scheduled for addition or removal) 
  will be lost.  

Contact, Development, Help
------------------------------

* If you have questions or like to contribute please
  subscribe to the `vadm mailinglist`_.  Without subscription
  you cannot post to the mailing list.  

* You may also drop by the #codespeak channel on irc.freenode.org. 

.. _`vadm mailinglist`: http://codespeak.net/mailman/listinfo/vadm
.. _`vadm tarball`: http://pypi.python.org/packages/source/v/vadm/vadm-0.6.0-beta5.tar.gz
