skip to navigation
skip to content

vcs-repo-mgr 0.15.1

Version control repository manager

The Python package vcs-repo-mgr provides a command line program and Python API to perform common operations (in the context of packaging/deployment) on version control repositories. It’s currently tested on Python 2.6, 2.7 and 3.4. Bazaar, Mercurial and Git repositories are currently supported.


To get started you have to install the package:

peter@macbook> pip install vcs-repo-mgr

You will also need Bazaar, Mercurial and/or Git installed (depending on the type of repositories you want to work with). Here’s how you install them on Debian/Ubuntu:

peter@macbook> sudo apt-get install bzr mercurial git-core

You now have the vcs-tool command available:

Usage: vcs-tool [OPTIONS] [ARGS]

Command line program to perform common operations (in the context of
packaging/deployment) on version control repositories. Supports Bazaar,
Mercurial and Git repositories.

Supported options:

  -r, --repository=REPOSITORY

    Select a repository to operate on by providing the name of a repository
    defined in one of the configuration files ~/.vcs-repo-mgr.ini and

    Alternatively the location of a remote repository can be given. The
    location should be prefixed by the type of the repository (with a '+' in
    between) unless the location ends in '.git' in which case the prefix is

  --rev, --revision=REVISION

    Select a revision to operate on. Accepts any string that's supported by the
    VCS system that manages the repository, which means you can provide branch
    names, tag names, exact revision ids, etc. This option is used in
    combination with the --find-revision-number, --find-revision-id and
    --export options.

    If this option is not provided a default revision is selected: 'last:1' for
    Bazaar repositories, 'master' for git repositories and 'default' (not
    'tip'!) for Mercurial repositories.

  -n, --find-revision-number

    Print the local revision number (an integer) of the revision given with the
    --revision option. Revision numbers are useful as a build number or when a
    simple, incrementing version number is required. Revision numbers should
    not be used to unambiguously refer to a revision (use revision ids for that
    instead). This option is used in combination with the --repository and
    --revision options.

  -i, --find-revision-id

    Print the global revision id (a string) of the revision given with the
    --revision option. Global revision ids are useful to unambiguously refer to
    a revision. This option is used in combination with the --repository and
    --revision options.

  -s, --sum-revisions

    Print the summed revision numbers of multiple repository/revision pairs.
    The repository/revision pairs are taken from the positional arguments to

    This is useful when you're building a package based on revisions from
    multiple VCS repositories. By taking changes in all repositories into
    account when generating version numbers you can make sure that your version
    number is bumped with every single change.


    Print a line containing a Debian control file field and value. The field
    name will be one of 'Vcs-Bzr', 'Vcs-Hg' or 'Vcs-Git'. The value will be the
    repository's remote location and the selected revision (separated by a '#'

  -u, --update

    Create/update the local clone of a remote repository by pulling the latest
    changes from the remote repository. This option is used in combination with
    the --repository option.

  -e, --export=DIRECTORY

    Export the contents of a specific revision of a repository to a local
    directory. This option is used in combination with the --repository and
    --revision options.

  -d, --find-directory

    Print the absolute pathname of a local repository. This option is used in
    combination with the --repository option.

  -v, --verbose

    Make more noise.

  -h, --help

    Show this message and exit.

The primary way to use the vcs-tool command requires you to create a configuration file:

peter@macbook> cat > ~/.vcs-repo-mgr.ini << EOF
type = git
local = /tmp/coloredlogs
remote =

Because the -r, --repository option accepts remote repository locations in addition to names it’s not actually required to create a configuration file. Of course this depends on your use case(s).

Below are some examples of the command line interface. If you’re interested in using the Python API please refer to the online documentation.

Updating repositories

If the configuration file defines a local and remote repository and the local repository doesn’t exist yet it will be created the first time you update it:

peter@macbook> vcs-tool --repository coloredlogs --update
2014-05-04 18:55:54 INFO Creating Git clone of at /tmp/coloredlogs ..
Cloning into bare repository '/tmp/coloredlogs'...
remote: Reusing existing pack: 96, done.
remote: Counting objects: 5, done.
remote: Compressing objects: 100% (5/5), done.
remote: Total 101 (delta 0), reused 0 (delta 0)
Receiving objects: 100% (101/101), 28.11 KiB, done.
Resolving deltas: 100% (44/44), done.

Later runs will pull the latest changes instead of performing a full clone:

peter@macbook> vcs-tool --repository coloredlogs --update
2014-05-04 18:55:56 INFO Updating Git clone of at /tmp/coloredlogs ..
 * branch HEAD -> FETCH_HEAD

Finding revision numbers/ids

Revision numbers are integer numbers that increment with every added revision. They’re very useful during packaging/deployment:

peter@macbook> vcs-tool --repository coloredlogs --revision master --find-revision-number

Revision ids (hashes) are hexadecimal strings that uniquely identify revisions. They are useful to unambiguously refer to a revision and its history (e.g while building a package you can embed the revision id as a hint about the origins of the package):

peter@macbook> vcs-tool --repository coloredlogs --revision master --find-revision-id

Exporting revisions

The repositories created by vcs-repo-mgr do not contain a working tree, just the version control files (in Git terminology this is called a “bare repository”). This has two reasons:

  1. Bare repositories help conserve disk space. This is insignificant for small repositories, but on large repositories it can make a noticeable difference. Especially if you’re using a lot of them :-)
  2. Bare repositories enforce the principle that the working tree shouldn’t be used during packaging (instead you should export the tree at a specific revision to a temporary directory and use that). This insistence on not using the working tree during packaging has two reasons:
    1. The working tree can contain files which are not under version control. Such files should certainly not be included in a package unintentionally.
    2. If the working tree of a repository is used, this makes it impossible to safely perform parallel builds from the same repository (the builds can corrupt each other’s working tree).

This means that if you want to do something with the files in the repository you have to export a revision to a (temporary) directory:

peter@macbook> vcs-tool --repository coloredlogs --export /tmp/coloredlogs-snapshot
2014-05-04 19:17:24 INFO Exporting revision master of /tmp/coloredlogs to /tmp/coloredlogs-snapshot ..

peter@macbook> ls -l /tmp/coloredlogs-snapshot
total 28K
drwxrwxr-x 2 peter peter 4.0K May  3 14:31 coloredlogs
drwxrwxr-x 3 peter peter 4.0K May  3 14:31 vim
-rw-rw-r-- 1 peter peter 1.1K May  3 14:31 LICENSE.txt
-rw-rw-r-- 1 peter peter   56 May  3 14:31
-rw-rw-r-- 1 peter peter 5.4K May  3 14:31 README.rst
-rwxrwxr-x 1 peter peter 1.1K May  3 14:31


The latest version of vcs-repo-mgr is available on PyPi and GitHub. For bug reports please create an issue on GitHub. If you have questions, suggestions, etc. feel free to send me an e-mail at


This software is licensed under the MIT license.

© 2015 Peter Odding.

File Type Py Version Uploaded on Size
vcs-repo-mgr-0.15.1.tar.gz (md5) Source 2015-08-19 23KB
  • Downloads (All Versions):
  • 33 downloads in the last day
  • 325 downloads in the last week
  • 1786 downloads in the last month