NAME

Stow - manage the installation of multiple software packages

SYNOPSIS

    my $stow = new Stow(%$options);

    $stow->plan_unstow(@pkgs_to_unstow);
    $stow->plan_stow  (@pkgs_to_stow);

    my %conflicts = $stow->get_conflicts;
    $stow->process_tasks() unless %conflicts;

DESCRIPTION

This is the backend Perl module for GNU Stow, a program for managing the installation of software packages, keeping them separate (/usr/local/stow/emacs vs. /usr/local/stow/perl, for example) while making them appear to be installed in the same place (/usr/local).

Stow doesn't store an extra state between runs, so there's no danger of mangling directories when file hierarchies don't match the database. Also, stow will never delete any files, directories, or links that appear in a stow directory, so it is always possible to rebuild the target tree.

CONSTRUCTORS

new(%options)

Required options

• dir - the stow directory

• target - the target directory

Non-mandatory options

See the documentation for the stow CLI front-end for information on these.

• conflicts

• simulate

• verbose

• paranoid

• compat

• test_mode

• adopt

• no-folding

• ignore

• override

• defer

N.B. This sets the current working directory to the target directory.

set_stow_dir([$dir])

Sets a new stow directory. This allows the use of multiple stow directories within one Stow instance, e.g.

    $stow->plan_stow('foo');
    $stow->set_stow_dir('/different/stow/dir');
    $stow->plan_stow('bar');
    $stow->process_tasks;

If $dir is omitted, uses the value of the dir parameter passed to the new() constructor.

METHODS

plan_unstow(@packages)

Plan which symlink/directory creation/removal tasks need to be executed in order to unstow the given packages. Any potential conflicts are then accessible via get_conflicts().

plan_stow(@packages)

Plan which symlink/directory creation/removal tasks need to be executed in order to stow the given packages. Any potential conflicts are then accessible via get_conflicts().

get_conflicts()

Returns a nested hash of all potential conflicts discovered: the keys are actions ('stow' or 'unstow'), and the values are hashrefs whose keys are stow package names and whose values are conflict descriptions, e.g.:

    (
        stow => {
            perl => [
                "existing target is not owned by stow: bin/a2p"
                "existing target is neither a link nor a directory: bin/perl"
            ]
        }
    )

get_conflict_count()

Returns the number of conflicts found.

get_tasks()

Returns a list of all symlink/directory creation/removal tasks.

get_action_count()

Returns the number of actions planned for this Stow instance.

invalidate_memoized_regexp($file)

For efficiency of performance, regular expressions are compiled from each ignore list file the first time it is used by the Stow process, and then memoized for future use. If you expect the contents of these files to change during a single run, you will need to invalidate the memoized value from this cache. This method allows you to do that.

BUGS

SEE ALSO

cpanm Stow

perl -MCPAN -e shell
install Stow