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

.. _install: install.html

Install via ``easy_install vadm`` or look at install_.

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  

Note that there is no explicit working copy.  In fact
it will be ``vadm`` which manages that working copy and 
you can type::

    vadm config

to see your current internal REPO/WC-configuration. 
Multiple users can checkout from the same repository.  Each
of the users will have its own internal "working copy". 

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. 

.. Note:: 

    ``vadm`` needs to execute as a non-root user that 
    has the right to execute ``sudo``.


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.