The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

snerp-projector - break a Git repository into projects

SYNOPSIS

        snerp-projector \
                --map paths-to-projects.txt \
                --db snanalyze-index.sqlite3 \
                --from monolithic-git-working-dir \
                --into new-parent-dir

DESCRIPTION

snerp-projector identifies and breaks up a monolithic Git repository into separate, smaller repositories for each subproject.

The original monolithic git repository (--from) is cloned for each anticipated subrpoject (listed in --map). The subproject clones are placed into a new parent directory (--into).

Subprojects are described in a YAML file, which contains a hash of hashes:

        project:
                gitdir: project/dir
                svndir: trunk/project/dir

For example:

        poe-loop-gtk:
                gitdir: polo-gtk
                svndir: trunk/polo-gtk

Needing both gitdir and svndir isn't ideal, but there hasn't been a better idea yet.

Repository Requirements

snerp-projector makes some assumptions about the repository. These may change in the future, faster if someone can contribute patches.

  • Each subproject lives entirely under a single directory.

  • The complete history for each subproject is worth preserving.

Subproject Types

Subprojects vary in structure. Each structure has its own requirements, which are outlined here.

Notes Applicable to All Project Types

In all cases, the original repository is cloned once for each subproject listed in the --map file.

The extraction of each subproject will modify most or all of the cloned repositories. Unrelated commits will be removed from each subproject's repository. As much of the subproject as possible will be removed from all other repositories.

Isolated Projects

Some projects are created as new directories and contain all new files. No other project contributes to them. No files are copied in from elsewhere in the repository.

These projects are easiest to split into their own repositories:

        git filter-branch \
                -f \
                --subdirectory-filter project/path \
                --tag-name-filter cat \
                --prune-empty \
                -- \
                --all

Spin-Off Projects

Spin-off projects include files copied or moved in from other projects. These pre-project files and commits contribute to the spin-off and its history, so they must be preserved. However, they may be discarded after the final contribution to the spin-off project.

Projects that don't contribute to spin-offs are removed entirely:

        git filter-branch \
                --index-filter 'git rm -r --cached --ignore-unmatch source/path' \
                master

Projects that do contribute are discontinued after the final contribution. Everything afterwards is removed. For example, if poe's last contribution to poe-extras was change df174613:

        git filter-branch \
                --index-filter 'git rm -r --cached --ignore-unmatch extras' \
                df174613..

That's a literal "..".

SEE ALSO

App::SnerpVortex - Main documentation for Snerp Vortex.

snanalyze - Analyze a Subversion dump, and produce an index database for other tools to process.

mnerp - Convert a Subversion repository to a flat filesystem or Git. Uses the snanalyze index, with help from the snassign tools, to intelligently branch and tag as it goes.

AUTHORS AND LICENSE

Snerp Vortex is Copyright 2010 by Rocco Caputo and contributors.

It is released under the same terms as Perl itself.