Repository files navigation

The Python package vcs-repo-mgr provides a command line program and PythonAPI to perform common operations (in the context of packaging/deployment) onversion control repositories. It's currently tested on Python 2.6, 2.7, 3.4,3.5 and 3.6 on Linux and Mac OS X.Bazaar,Mercurial andGit repositoriesare supported.

The vcs-repo-mgr package is available onPyPI which means installationshould be as simple as:

$ pip install vcs-repo-mgr

There's actually a multitude of ways to install Python packages (e.g. theperuser site-packages directory,virtual environments or just installingsystem wide) and I have no intention of getting into that discussion here, soif this intimidates you then read up on your options before returning to theseinstructions ;-).

You will also needBazaar,Mercurial and/orGit installed (depending on thetype of repositories you want to work with). Here's how you install them onDebian and Ubuntu based systems:

$ sudo apt-get install bzr mercurial git-core

There are two ways to use the vcs-repo-mgr package: As the command lineprogramvcs-tool and as a Python API. For details about the Python APIplease refer to the API documentation available onRead the Docs. Thecommand line interface is described below.

Usage: vcs-tool [OPTIONS] [ARGS]

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

Supported options:

The primary way to use thevcs-tool command requires you to create aconfiguration file:

$ cat>~/.vcs-repo-mgr.ini<<EOF[coloredlogs]type = gitlocal = /tmp/coloredlogsremote = git@github.com:xolox/python-coloredlogs.gitEOF

Because the-r,--repository option accepts remote repository locationsin 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 inusing the Python API please refer to theonline documentation.

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

$ vcs-tool --repository coloredlogs --update2014-05-04 18:55:54 INFO Creating Git clone of git@github.com:xolox/python-coloredlogs.git 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:

$ vcs-tool --repository coloredlogs --update2014-05-04 18:55:56 INFO Updating Git clone of git@github.com:xolox/python-coloredlogs.git at /tmp/coloredlogs ..From github.com:xolox/python-coloredlogs* branch HEAD -> FETCH_HEAD

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

$ vcs-tool --repository coloredlogs --revision master --find-revision-number24

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

$ vcs-tool --repository coloredlogs --revision master --find-revision-idbce75c1eea88ebd40135cd45de716fe9591e348c

By default the repositories created by vcs-repo-mgr do not contain a working tree,just the version control files (inGit terminology this is called a "barerepository"). This has two reasons:

1. Bare repositories help conserve disk space. This is insignificant for smallrepositories, 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 beused during packaging (instead you should export the tree at a specificrevision to a temporary directory and use that). This insistence on notusing the working tree during packaging has two reasons:
   1. The working tree can contain files which are not under version control.Such files should certainlynot be included in a packageunintentionally.
   2. If the working tree of a repository is used, this makes it impossible tosafely perform parallel builds from the same repository (the builds cancorrupt each other's working tree).

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

$ vcs-tool --repository coloredlogs --export /tmp/coloredlogs-snapshot2014-05-04 19:17:24 INFO Exporting revision master of /tmp/coloredlogs to /tmp/coloredlogs-snapshot ..$ ls -l /tmp/coloredlogs-snapshottotal 28Kdrwxrwxr-x 2 peter peter 4.0K May  3 14:31 coloredlogsdrwxrwxr-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 MANIFEST.in-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 setup.py

This section is currently a "braindump" which means I haven't committed to anyof these improvements, I'm just thinking out loud ;-).

Improve interactive repository selection

Two improvements for interactive usage of thevcs-tool program:

• Automatically load a repository's configuration when a pathname is giventhat matches an entry in a configuration file (right now you need to givethe repository's name in order to load its configuration).
• Do the obvious thing when no repository is specified on the command line butthe working directory matches a configured repository.

Wildcard matching in configuration files

It might be interesting to support shell wildcard matching against localdirectory names to apply a default configuration to a group of repositories?

Enable more extensive customization

Right now the version control commands are hard coded and not easy tocustomize for those cases where the existing API gets you 90% of where youwant to be but makes that last 10% impossible. Technically this is alreadypossible through subclassing, but a more lightweight solution wouldcertainly be nice to have :-).

This section documents known issues that users may run into.

Bazaar and Mercurial are both written in Python and available on PyPI and assuch I included them in the installation requirements of vcs-repo-mgr,because I couldn't think of a good reason not to.

Adding support for Python 3 to vcs-repo-mgr made things more complicatedbecause Bazaar and Mercurial didn't support Python 3, leading to installationerrors. To cope with this problem the Bazaar and Mercurial requirements weremade conditional on the Python version:

• On Python 2 the Bazaar and Mercurial packages would be installed togetherwith vcs-repo-mgr.
• On Python 3 the user was instead responsible for making sure that Bazaar andMercurial were installed (for example using system packages).

This works fine because vcs-repo-mgr only invokes Bazaar and Mercurial usingthe command line interfaces so it doesn't matter whether the version controlsystem is using the same version of Python as vcs-repo-mgr.

Since then the installation of the Bazaar package has started failing on PyPy,unfortunately this time there is no reliable and backwards compatible way tomake the Bazaar dependency optional in wheel distributionsdue to bugs insetuptools.

When I investigated support for environment markers that match Pythonimplementations (refer to the link above) I decided that instead of writing asetup script full of nasty and fragile hacks I'd rather just drop official(tested) support for PyPy, as silly as the reason for it may be.

The latest version of vcs-repo-mgr is available onPyPI andGitHub. Thedocumentation is hosted onRead the Docs and includes achangelog. For bugreports please create an issue onGitHub. If you have questions, suggestions,etc. feel free to send me an e-mail atpeter@peterodding.com.

This software is licensed under theMIT license.

© 2018 Peter Odding.