/ 
CPAN-InGit-0.000_002
/ CPAN::InGit

NAME

CPAN::InGit - Manage custom CPAN trees to pin versions for your projects

SYNOPSIS

my $cpan_repo= CPAN::InGit->new(repo => $path_to_git_repo);
my $mirror_tree= $cpan_repo->branch_mirror($git_branch_name);
# (all interesting methods are found on Mirror objects)

DESCRIPTION

CPAN::InGit is a concept that your entire CPAN mirror (or maybe more correctly a DarkPAN) lives within a Git repository. You designate a branch for each of your perl environments (such as one branch per application) and that branch contains ONLY the dist tarballs used by that project, and an index of the packages within.

Features

  • It's your own private CPAN (DarkPAN) with all the benefits that entails. (such as private dists or patching public dists)

  • The data is stored in Git, so it's version controlled and compressed. This module reads directly from the Git repo storage without needing a checkout.

  • The server serves each branch as its own mirror URL, so it's actually like an unlimited number of DarkPANs hosted on the same server. Each branch indexes only the dist files you have added to that branch, and only one version per dist.

  • There is a web interface that helps you pull new versions of dists from public CPAN, review the changes and compare diffs of the module code, chain-pull new dependencies, and commit the new dist versions into a branch. The web interface also helps you apply patches to public dists and maintains the history of those patches.

  • You can revert to a previous environment for your application with a simple "git revert". (or use the web interface)

  • Removes the need for cpanfile.snapshot or carton, because now the DarkPAN mirror is versioning your environment for each application.

ATTRIBUTES

git_repo

An instance of Git::Raw::Repository (which wraps libgit2.so) for accessing the git structures. You can pass this attribute to the constructor as a simple directory path which gets inflated to a Repository object.

git_author_name

Name used for commits generated by this library. Defaults to 'CPAN::InGit'

git_author_email

Email used for commits generated by this library. Defaults to 'CPAN::InGit@localhost'

useragent

The Mojo::UserAgent object used when downloading files from the real CPAN.

METHODS

get_archive_tree

$mirror= $cpan_repo->get_archive_tree($branch_or_tag_or_id);

Return a ArchiveTree object for the given branch name, git tag, or commit hash. This branch must look like an archive (having /cpan_ingit.json) or it will return undef.

create_archive_tree

$mirror= $cpan_repo->create_archive_tree($branch_name, %params);

Create a new mirror branch. The branch must not already exist.

lookup_tree

$tree= $cpan_repo->lookup_tree($branch_or_tag_or_commit);
($tree, $origin)= $cpan_repo->lookup_tree($branch_or_tag_or_commit);

Return the Git::Raw::Tree object for the given branch name, git tag, or commit hash. Returns undef if not found. In list context, it returns both the tree and the origin object (commit, branch, or tag) for that tree.

add_git_tree_to_tar

$mirrorInGit->add_git_tree_to_tar($tar, $path, $tree);

This utility function adds Git trees to a tar archve, calling "add_git_dirent_to_tar" for each entry. $path provides the name for the root of the tree within the archive. undef or empty string means the tree will be the root of the archive.

add_git_dirent_to_tar

$mirrorInGit->add_git_dirent_to_tar($tar, $path, $dirent);

This utility function adds Git directory entries to a tar archve. It recurses subdirectories and handles symlinks. The $path is used for the destination name instead of $dirent->name.

new_signature

Returns a Git::Raw::Signature that will be used for commits authored by this module. Signatures contain a timestamp, so the library generates new signatures frequently during operation.

lookup_versions

$version_list= $cpan_repo->lookup_versions($module_name);

This returns a list of all versions of that module which are already cached in any Mirror of this repo, and also any version which is available from any of the upstream mirrors listed in "upstream_mirrors".

process_distfile

my $index= $darkpan->process_distfile(
  tree      => $mirror_tree,
  file_path => $path,
  file_data => \$bytes,
  untar     => $bool,   # whether to extract tar file into the tree
);

VERSION

version 0.000_002

AUTHOR

Michael Conrad <mike@nrdvana.net>

COPYRIGHT AND LICENSE

This software is copyright (c) 2025 by Michael Conrad, and IntelliTree Solutions.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.