Philippe Bruhat (BooK) > Git-CPAN-Hook-0.03 > Git::CPAN::Hook

Download:
Git-CPAN-Hook-0.03.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.03   Source  

NAME ^

Git::CPAN::Hook - Commit each install done by CPAN.pm in a Git repository

SYNOPSIS ^

    # install the hooks in CPAN.pm
    $ perl -MGit::CPAN::Hook -e install

    # put your local::lib under Git control
    $ perl -MGit::CPAN::Hook -e init ~/perl5

    # use CPAN.pm / cpan as usual
    # every install will create a commit in the current branch

    # uninstall the hooks from CPAN.pm's config
    $ perl -MGit::CPAN::Hook -e uninstall

DESCRIPTION ^

Git::CPAN::Hook adds Git awareness to the CPAN.pm module installer. Once the hooks are installed in CPAN.pm's configuration, each and every module installation will result in a commit being done in the installation directory/repository.

All the setup you need is described in the SYNOPSIS. Read further if you are interested in the gory details.

Rationale

This module is a proof of concept.

Then I want to experiment with a repository of installed stuff, especially several versions of the same distribution. And then start doing fancy things like uninstalling a single distribution, testing my modules against different branches (each test environment is only a "git checkout" away!), creating a full install from scratch by applying "install patches", etc.

There are two parts to maintaining a CPAN installation as a Git repository:

If this proves useful in any way, it shouldn't be too hard to port to CPAN clients that support hooks and plugins. It might be a little more difficult to use the terminate and stay resident approach I used on CPAN.pm on other clients, as they probably have a san^Hfer configuration file format.

Configuration

Git::Repository::Hook is called by your CPAN client after each installation, to perform a commit in the installation directory.

Because Git::CPAN::Hook doesn't know a priori where your CPAN client has installed the files, it processes @INC looking for Git repositories. To avoid unexpected commits in development repositories, your CPAN repository must have been activated.

This is done by setting the following configuration in your repository:

    [cpan-hook]
        active = true

For simplicity, Git::CPAN::Hook should ignore .packlist files, as well as perllocal.pod.

    $ perl -le 'print for qw( .packlist perllocal.pod )' >> .gitignore

The whole point of having your CPAN installation under Git control is to have multiple branches. They should all start with the basic, empty directory (basically, containing only the .gitignore file). This initial commit will be tagged empty.

This is a lot of setup, so there is a one line shortcut (assuming the directory you want to track is ~/perl5:

    $ perl -MGit::CPAN::Hook -e init ~/perl5

Hooking Git::CPAN::Hook in CPAN.pm

Because CPAN.pm is ubiquitous, it was the initial target client for Git::CPAN::Hook. Because it doesn't support hooks, hook support had to be hacked in.

This is done by adding some code to activate the hooks in the configuration file of CPAN.pm, which happens to be a Perl script that is eval'ed. ;-)

Again, there is a shortcut to install the hook:

    $ perl -MGit::CPAN::Hook -e install

and to uninstall it:

    $ perl -MGit::CPAN::Hook -e uninstall

INTEGRATION WITH OTHER CPAN CLIENTS ^

Git::CPAN::Hook currently only explicitely supports CPAN.pm. It shouldn't be too hard to integrate with any CPAN client that supports plugins.

METHODS ^

The following methods are available to write plugins/wrappers/hooks for your CPAN client.

commit( $dist )

Browse all directories in @INC, looking for an "active" repository (i.e. with the Git configuration cpan-hook.active item set to true), with local changes, and commit them with $dist as the log message. $dist is expected to be the full distribution name, e.g. B/BO/BOOK/Git-CPAN-Hook-0.02.tar.gz.

This method is meant to be called right after the installation of an individual distribution, so that newly added/modified files will be committed to the repository.

AUTHOR ^

Philippe Bruhat (BooK), <book at cpan.org>

HISTORY AND ACKNOWLEDGEMENTS ^

The initial idea for this module comes from a conversation between Andy Armstrong, Tatsuhiko Miyagawa, brian d foy and myself (each having his own goal in mind) at the Perl QA Hackathon 2010 in Vienna.

My own idea was that it would be neat to install/uninstall distributions using Git to store the files, so that I could later develop some tools to try all kinds of crazy combinations of modules versions and installations. I already saw myself bisecting on a branch with all versions of a given dependency...

To do that and more, I needed a module to control Git from within Perl. So I got distracted into writing Git::Repository.

At the Perl QA Hackathon 2011 in Amsterdam, the discussion came up again with only Andy Armstrong and myself, this time. He gently motivated me into "just doing it", and after a day of experimenting, I was able to force CPAN.pm to create a commit after each individual installation.

TODO ^

Here are some of the items on my list:

BUGS ^

Please report any bugs or feature requests to bug-git-cpan-hook at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=GIT-CPAN-Hook. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT ^

You can find documentation for this module with the perldoc command.

    perldoc Git::CPAN::Hook

You can also look for information at:

COPYRIGHT ^

Copyright 2011 Philippe Bruhat (BooK).

LICENSE ^

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.

syntax highlighting: