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

**vadm** is a simple svn-like command line tool for 
versioning unix system files, ownership and permission
information.  It uses subversion_ under the hood and maps 
all files that you decide to version into a single 
per-user repository.  As a single adminstrator you can 
decide to selectively and non-intrusively version some 
files through your own home directory. 

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::
    :local:
    :depth: 2

.. _subversion: http://subversion.tigris.org 

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 

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 also installs the py lib dependency).

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

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

.. _`install the py lib without setuptools`: http://pylib.org/download.html#no-setuptools

1. `install the py lib without setuptools`_. 

2. download the `vadm tarball`_  and install it like this (substitute
   the version number as appropriate)::

     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 can 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 needs to execute 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

- You can transfer your local repository to a remote location
  and then do a ``vadm checkout`` using an https or svn+ssh scheme. 

- **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
------------------------------

* `google code vadm tracker`_ 

* `vadm mailinglist`_ (requires subscription) for general 
  questions 

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

* If all else fails you may contact holger.krekel at google com. 

.. _`google code vadm tracker`: http://code.google.com/p/vadm/issues/list
.. _`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
