view release on metacpan or  search on metacpan

lib/App/Transpierce.pm  view on Meta::CPAN

package App::Transpierce;
$App::Transpierce::VERSION = '0.002';
use v5.10;
use strict;
use warnings;

1;

__END__

=head1 NAME

App::Transpierce - backup and modify important files

=head1 SYNOPSIS

	# exports the script into the current directory
	transpierce --self-export

	# copies the script to the server
	scp transpierce myuser@remote:~/transpierce

	# log into the server, create a directory for the current task
	ssh myuser@remote
	mkdir dirty_production_task

	# create transpierce.conf file, which describes files to be altered
	echo "target /production/directory" >> dirty_production_task/transpierce.conf
	echo "production/file.ext" >> dirty_production_task/transpierce.conf

	# see what actions will be taken
	transpierce --describe dirty_production_task

	# set up the environment for that task
	transpierce dirty_production_task

	# recommended: verify the contents of .sh files
	cat dirty_production_task/*.sh

	# recommended: set up a git repository (if it is available)
	cd dirty_production_task
	git init
	git add -A
	git commit -m "Initial setup"

=head1 DESCRIPTION

This distribution provides C<transpierce> script which can be used for per-task
management of files which must be backed up before modification.

Transpierce means to pierce through. The module makes it easier penetrate
system files and alter them by working on local copies. You only poke single
holes in it by performing file deployment and (if needed) backup restoration.
If you think that's not how it's supposed to be done, you're right - but
sometimes it is what needs to be done.

Suppose you must reproduce a bug that only happens under a very specific
environment. Or you have to quickly hotfix something and full release cycle
will not be fast enough. Do you change live files? Or make copies as backups
and then do modifications? Are you sure you restored all unwanted changes?

This script will set up a small working environment for you, which consists of:

=over

=item * C<restore> directory, containing original files (not meant to be changed)

=item * C<deploy> directory, where you can make your changes

=item * C<restore.sh> script, which will restore original files from C<restore> directory

=item * C<deploy.sh> script, which will copy files to their locations from C<deploy> directory

=item * C<diff.sh> script, which will check whether files in C<restore> directory differ from original files

=back

This environment is best made in your home directory, far away from important files.

=head2 Configuration

The list of files is set using C<transpierce.conf> file. Each file is in its own line:

	/prod/lib/System.pm
	/prod/script.pl
	/etc/apache2/sites-available/mysite.conf

During copying the files to C<restore> and C<deploy> their paths are flattened, like so:

	__prod__lib__System.pm
	__prod__script.pl
	__etc__apache2__sites-available__mysite.conf

If files in your C<transpierce.conf> contain whitespace, you will need to quote
using either single or double quotes:

	target "/dir/with space/file_with_space"