From: Robert 'phaylon' Sedlacek <r.sedlacek@shadowcat.co.uk>
Date: Tue, 29 May 2012 00:23:39 +0000 (+0000)
Subject: documentation
X-Git-Tag: v0.000001~12
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=scpubgit%2FFile-Tree-Snapshot.git;a=commitdiff_plain;h=ed0958d733282926c3c97de39f63408df056d429

documentation
---

diff --git a/lib/File/Tree/Snapshot.pm b/lib/File/Tree/Snapshot.pm
index edd5849..9b883f7 100644
--- a/lib/File/Tree/Snapshot.pm
+++ b/lib/File/Tree/Snapshot.pm
@@ -101,3 +101,104 @@ sub find_files {
 }
 
 1;
+
+=head1 NAME
+
+File::Tree::Snapshot - Snapshot files in a git repository
+
+=head1 SYNOPSIS
+
+    use File::Tree::Snapshot;
+
+    my $tree = File::Tree::Snapshot->new(
+        storage_path => '/path/to/tree',
+    );
+
+    $tree->create
+        unless $tree->exists;
+
+    # modify files, see methods below
+
+    $tree->commit;
+    # or
+    $tree->reset;
+
+=head1 DESCRIPTION
+
+This module manages snapshots of file system trees by wrapping the C<git>
+command line interface. It currently only manages generating the snapshots.
+
+The directories are standard Git repositories and can be accessed in the
+usual ways.
+
+=head1 ATTRIBUTES
+
+=head2 storage_path
+
+The path to the tree that should hold the files that are snapshot. This
+attribute is required.
+
+=head2 allow_empty
+
+If this attribute is set to true, commits will be created even if no changes
+were registered.
+
+=head1 METHODS
+
+=head2 new
+
+    my $tree = File::Tree::Snapshot->new(%attributes);
+
+Constructor. See L</ATTRIBUTES> for possible parameters.
+
+=head2 file
+
+    my $path = $tree->file(@relative_path_parts_to_file);
+
+Takes a set of path parts and returns the path to the file inside the
+storage.
+
+=head2 open
+
+    my $fh = $tree->open($mode, $file, %options);
+
+Opens a file within the storage. C<$mode> is passed straight to
+L<perlfunc/open>. The C<$file> is a relative path inside the storage.
+
+Possible options are:
+
+=over
+
+=item * C<is_absolute>
+
+If set to true the C<$file> will be assumed to already be an absolute
+path as returned by L</file>, instead of a path relative to the storage.
+
+=item * C<mkpath>
+
+Create the path to the file if it doesn't already exist.
+
+=back
+
+=head2 create
+
+    $tree->create;
+
+Create the directory (if it doesn't exist yet) and initialize it as a
+Git repository.
+
+=head2 exists
+
+    my $does_exist = $tree->exists;
+
+Returns true if the storage is an initialized Git repository.
+
+=head2 commit
+
+Will commit the changes made to the tree to the Git repository.
+
+=head2 reset
+
+Rolls back the changes since the last snapshot.
+
+=cut