longleaf 0.2.0.pre.1 → 0.3.0

data/.yardopts

@@ -0,0 +1 @@
+--output-dir docs/rdocs

data/Gemfile

@@ -1,4 +1,19 @@
 source 'https://rubygems.org'
 
-# Specify your gem's dependencies in longleaf.gemspec
 gemspec
+
+group :postgres, optional: true do
+  gem 'pg', '>= 1.0.0'
+end
+
+group :sqlite, optional: true do
+  gem 'sqlite3'
+end
+
+group :mysql2, optional: true do
+  gem 'mysql2', ">= 0.5.0"
+end
+
+group :mysql, optional: true do
+  gem 'mysql'
+end

data/README.md

@@ -1,4 +1,6 @@
 # Longleaf
+Code: [![CircleCI](https://circleci.com/gh/UNC-Libraries/longleaf-preservation.svg?style=svg)](https://circleci.com/gh/UNC-Libraries/longleaf-preservation)
+
 Longleaf is a command-line tool which allows users to configure a set of storage locations and define custom sets of preservation services to run on their contents. These services are executed in response to applicable preservation events issued by clients. Its primary goal is to provide tools to create a simple and customizable preservation environment.  Longleaf:
 
 * Offers a predictable command-line interface and integrates with standard command-line tools.
@@ -9,7 +11,29 @@ Longleaf is a command-line tool which allows users to configure a set of storage
 
 ## Installation
 
-Add this line to your application's Gemfile:
+There are two primary ways to install Longleaf, depending on how you intend to use it:
+
+#### Standalone gem
+
+To use Longleaf as a command-line application, the gem can be installed using:
+
+```
+$ gem install longleaf
+```
+
+Or it may be built from source:
+
+```
+$ git clone git@github.com:UNC-Libraries/longleaf-preservation.git
+$ cd longleaf-preservation
+$ bin/setup
+$ bundle exec rake install # builds the gem
+$ gem install --local pkg/longleaf* # installs gem
+```
+
+#### Applicaton dependency
+
+To make use of longleaf as a dependency of your application, add this line to your application's Gemfile:
 
 ```ruby
 gem 'longleaf'
@@ -17,23 +41,27 @@ gem 'longleaf'
 
 And then execute:
 
-    $ bundle
-
-Or install it yourself as:
-
-    $ gem install longleaf
+```
+$ bundle
+```
 
 ## Usage
 
 #### Register a file
 In order to register a new file with Longleaf, use the register command:
-`longleaf register -c <config.yml> -f <path to file>`
+
+```
+longleaf register -c <config.yml> -f <path to file>
+```
 
 In the case that a file's content is replaced, the file can be re-registered by providing the `--force` flag.
 
 #### Validate configuration files
 Application configuration files can be validated prior to usage with the following command:
-`longleaf validate_config -c <config.yml>`
+
+```
+longleaf validate_config -c <config.yml>
+```
 
 #### Output and logging
 
@@ -42,21 +70,47 @@ The primary output from Longleaf is directed to STDOUT, and contains both succes
 Additional logging is sent to STDERR. To control the level of logging, you may provide the `--log-level` parameter, which expects the standard [Ruby Logger levels](https://ruby-doc.org/stdlib-2.4.0/libdoc/logger/rdoc/Logger.html). The default log level is 'WARN'.
 
 Messages sent to STDOUT are duplicated to STDERR at 'INFO' level, so they are excluded by default. In order to store an ongoing log of activity and errors, you would perform the following:
-`longleaf <command> --log-level 'INFO' 2> /logs/longleaf.log`
+
+```
+longleaf <command> --log-level 'INFO' 2> /logs/longleaf.log
+```
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rspec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. 
 
-To run Longleaf with local changes without needing to do a local install, you may run `bundle exec exe/longleaf <command>`.
+To perform the tests, run:
+```
+bundle exec rspec
+```
 
-To install this gem onto your local machine, run `bundle exec rake install`. This will allow you to run `longleaf <command>` and places the gem into `pkg/`. Note: Only files committed to git will be included in the installed gem.
+To run Longleaf with local changes without needing to do a local install, you may run:
+```
+bundle exec exe/longleaf <command>
+```
+
+To install this gem onto your local machine, run:
+```
+bundle exec rake install
+```
+
+This places a newly built gem into the `pkg/` directory. This gem may then be installed in order to run commands in the `longleaf <command>` form.
+_Note:_ Only files committed to git will be included in the installed gem.
 
 To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
+## Indexing
+To use an index to improve performance, you will need to install the database drivers separately or bundle longleaf with the driver you wish to use:
+
+```
+bundle install --with postgres
+```
+
+Options include: postgres, mysql2, mysql, sqlite, amalgalite
+
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://gitlab.lib.unc.edu/cdr/longleaf.
+Bug reports and pull requests are welcome on GitHub at https://github.com/UNC-Libraries/longleaf-preservation.
 
 
 ## License

data/Rakefile

@@ -1,6 +1,12 @@
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
+require "yard"
 
 RSpec::Core::RakeTask.new(:spec)
 
 task :default => :spec
+
+YARD::Rake::YardocTask.new do |t|
+  t.options = ['--private', '--protected']
+  t.stats_options = ['--list-undoc']
+end

data/bin/setup

@@ -1,8 +1,23 @@
 #!/usr/bin/env bash
 set -euo pipefail
 IFS=$'\n\t'
+
+INSTALL_DEST=(--path '.bundle/')
+
+while [[ $# -gt 0 ]]
+do
+  key="$1"
+
+  case $key in
+  -s|--system)
+    INSTALL_DEST=(--system)
+    shift # past argument
+    ;;
+  esac
+done
+
 set -vx
 
-bundle install
+bundle install ${INSTALL_DEST[@]} --without ""
 
 # Do any other automated setup that you need to do here

data/docs/aboutlongleaf.md

@@ -0,0 +1,28 @@
+## About Longleaf
+
+Longleaf, developed at the University of North Carolina at Chapel Hill University Libraries, is an open-source, portable digital preservation tool, designed to enable the creation and application of highly configurable preservation plans for large and varied collections of digital content across multiple systems.
+
+Longleaf addresses challenges we have encountered over the past 20 years of growing and managing our digital collections infrastructure, which we feel are shared by other institutions:
+
+1. Preservation activities being applied to files based on system affiliation (i.e. repository platform or lack thereof) rather than the needs of the content.
+
+1. Difficulty maintaining an ideal schedule of fixity checks as the sizes of our collections grow.
+
+1. Physical and computational costs to servers and storage devices imposed by ongoing cryptographic checksum algorithms (Altman et al., 2013).
+
+1. Difficulty gradually introducing cloud storage services into our replication strategy for vulnerable files.
+
+The goal for Longleaf is to provide organizations with a flexible tool for creating and implementing tailored preservation practices across the scope of their content, based on appropriate levels of digital preservation need (Phillips, Bailey, Goethals, & Owens, 2013). To this end, we have designed Longleaf according to the principles of high “software availability” (Davidson & Casden, 2016) that prioritize ease of use by a broad set of users in a variety of environments. 
+
+The Longleaf application is a command-line utility that will run on any modern Linux operating system with only a ruby interpreter. Longleaf can be applied to any content storage system with a file system, and requires no repository, no external database, and no storage system other than the file system. It can be run completely from the command line or triggered by arbitrary external systems (e.g. initiated on file ingest). Preservation processes are targeted at the file and storage level rather than through a repository system intermediary, allowing files managed in temporary storage or non-preservation asset management systems to benefit from the same replication and verification processes as those ingested into preservation repositories. For example, in our own digital collections context, we will be applying Longleaf to content across a wide variety of systems, including files managed entirely on shared drives, files managed by Fedora-based repositories, as well as digitization masters managed by CONTENTdm. 
+
+Longleaf’s modular architecture and flexible configuration system reduce the interference of repository system constraints, to enable needs-based digital preservation planning processes such as evaluating and configuring specific preservation activities across subsets of larger collections. For our collections, we are using Longleaf to begin addressing specific challenges such as managing the physical and computational costs of large-scale fixity verification, and integrating storage endpoints with different access costs. For example, we are increasing coverage of ongoing and transactional fixity checks (Gallinger, Bailey, Cariani, Owens, & Altman, 2017) by providing typical cryptographic checksums alongside more scaleable non-cryptographic checks and filesystem checks. We can also determine more appropriate replication and verification schedules and techniques overall, based on the characteristics of both the source and destination storage locations for content. 
+
+## References
+Altman, M., Bailey, J., Cariani, K., Gallinger, M., Mandelbaum, J., & Owens, T. (2013). NDSA Storage Report: Reflections on National Digital Stewardship Alliance Member Approaches to Preservation Storage Technologies. D-Lib Magazine, 19(5/6). https://doi.org/10.1045/may2013-altman
+
+Davidson, B., & Casden, J. (2016). Beyond open source. Code4Lib Journal, Issue 31. Retrieved from http://journal.code4lib.org/articles/11148
+
+Gallinger, M., Bailey, J., Cariani, K., Owens, T., & Altman, M. (2017). Trends in Digital Preservation Capacity and Practice: Results from the 2nd Bi-annual National Digital Stewardship Alliance Storage Survey. D-Lib Magazine, 23(7/8). https://doi.org/10.1045/july2017-gallinger
+
+Phillips, M., Bailey, J., Goethals, A., & Owens, T. (2013). The NDSA levels of digital preservation: Explanation and uses. In Archiving Conference (Vol. 2013, pp. 216–222). Society for Imaging Science and Technology.

data/docs/extra.css

@@ -0,0 +1,32 @@
+ /* added link colors to text that's not in side nav menu */
+
+.rst-content a:link { color:#0000FF; text-decoration:none; font-weight:normal; }
+
+.rst-content a:visited { color:#800080; text-decoration:none; font-weight:normal; }
+
+.rst-content a:hover { color:aqua; text-decoration:none; font-weight:normal; }
+
+.rst-content a:active { color:seagreen; text-decoration:none; font-weight:normal; }
+
+
+/*  changed background colors in side nav menu */
+
+.wy-side-nav-search {
+  background-color: mediumseagreen;
+  }
+ 
+.wy-menu-vertical span {
+  /*  line-height: 18px;*/
+    line-height: 20px;
+
+    padding: 0.4045em 1.618em;
+    display: block;
+    position: relative;
+    font-size: 90%;
+    color: #838383;
+}
+
+.wy-nav-side {
+    background: ##404040;
+}
+/*

data/docs/index.md

@@ -0,0 +1,19 @@
+## Longleaf Project Overview
+
+Welcome to the Longleaf Project Documentation site.
+
+This site contains supporting documentation for the Longleaf software project, currently in development by The University of North Carolina at Chapel Hill's University Libraries.  
+
+Longleaf is free, open-source software for creating highly configurable digital preservation environments. Longleaf provides a repository-agnostic command-line utility that enables users to configure and apply preservation processes such as monitoring and replication at the file level. Users can define preservation services using Longleaf's base set of commands, and then apply these preservation scripts to a set of user-defined storage locations that are relevant to the user's specific context.
+
+For a step-by-step tutorial of Longleaf's basic functionality, the ["Basic Usage" page](quickstart.md) in this site walks through Longleaf's core operations using a pre-configured example data directory.
+
+## Project URLs
+
+Code repository [Longleaf-preservation ](https://github.com/UNC-Libraries/longleaf-preservation)
+
+## Project Participants
+
+* Ben Pennell, Technical lead and software developer
+* Jason Casden, Product lead
+* Morgan McKeehan, Documentation lead

data/docs/install.md

@@ -0,0 +1,66 @@
+# Installing Longleaf
+
+### Ruby and other Prerequisites
+Longleaf requires Ruby 2.3 or higher.
+
+There also are optional gem dependencies if the user wishes to use an index to improve performance.
+
+Additionally, Longleaf scripts rely on common Unix programs. In Mac OS X and Linux operating systems, these programs will likely already be installed, but some of these tools, such as `rsync` may be missing from a Windows system unless you have installed them.
+
+### Download Longleaf
+Download Longleaf from UNC Chapel Hill's University Libraries [Longleaf github repository](https://github.com/UNC-Libraries/longleaf-preservation).
+
+### Install Longleaf
+
+There are two ways to install Longleaf, depending on how you intend to use it:
+
+**1. Standalone gem**
+
+To use Longleaf as a command-line application, the gem can be installed using:
+
+    $ gem install longleaf
+
+Or it may be built from source:
+
+    $ git clone git@github.com:UNC-Libraries/longleaf-preservation.git
+    $ cd longleaf-preservation
+    $ bin/setup --system
+    $ bundle exec rake install # builds the gem
+    $ gem install --local pkg/longleaf* # installs gem
+
+**2. Application dependency**
+
+To include longleaf as a dependency in an application, add this line to your application's Gemfile:
+
+```ruby
+gem 'longleaf'
+```
+
+And then execute:
+
+    $ bundle
+
+### Confirm Longleaf Installation
+If you have installed Longleaf using the "Standalone gem" approach, you can check to make sure that the installation succeeded by typing the following into your terminal:
+
+```
+longleaf
+```
+
+You should see the Longleaf help page:   
+```
+Commands:
+  longleaf --version          # Prints the Longleaf version number.
+  longleaf deregister         # Deregister files with Longleaf
+  longleaf help [COMMAND]     # Describe available commands or one specific command
+  longleaf preserve           # Perform preservation services on files with Longleaf
+  longleaf register           # Register files with Longleaf
+  longleaf reindex            # Perform a full reindex of file metadata stored within the configured storage locations.
+  longleaf setup_index        # Sets up the structure of the metadata index, if one is configured using the system configuration file provide...
+  longleaf validate_config    # Validate an application configuration file, provided using --config.
+  longleaf validate_metadata  # Validate metadata files.
+
+
+```
+### Installation Success!   
+If the Longleaf Help page printed successfully, you are ready to proceed to the [Basic Usage tutorial](quickstart.md) to try out basic Longleaf functionality.

data/docs/ll-example/config-example-relative.yml

@@ -0,0 +1,33 @@
+# Storage locations below use relative paths. When validating and using 
+# the configuration file, paths for the storage locations will be evaluated 
+# relative to the location of the configuration file. In this example tutorial, 
+# the storage locations are directories ('files-dir' and 'replica-files')
+# located at the same level as the config file, within the ll-example 
+# directory.
+
+locations:
+    data-directory:
+      path: files-dir
+      metadata_path: metadata-dir
+    backup-directory:
+      path: replica-files
+      metadata_path: replica-metadata
+services:
+  example_replication:
+    work_script: 'rsync_replication_service'
+    to:
+      - backup-directory
+  example_fixity:
+    work_script: 'fixity_check_service'
+    frequency: 30 seconds
+    absent_digest: generate
+    algorithms:
+      - sha1
+service_mappings:
+  - locations: data-directory
+    services:
+      - example_replication
+      - example_fixity
+  - locations: backup-directory
+    services:
+        - example_fixity

data/docs/ll-example/files-dir/LLexample-TOCHANGE.txt

@@ -0,0 +1,15 @@
+## MAKE CHANGES TO THIS FILE
+
+* make any changes here! 
+* ( insert changed text    ) 
+
+## Longleaf
+Longleaf is a command-line tool which allows users to configure a set of storage locations and define custom sets of preservation services to run on their contents. These services are executed in response to applicable preservation events issued by clients. Its primary goal is to provide tools to create a simple and customizable preservation environment.  
+
+Longleaf:
+
+* Offers a predictable command-line interface and integrates with standard command-line tools.
+* Offers configurable and customizable criteria based preservation workflows.
+* Provides a base set of tools and a framework for building extensions.
+* Provides activity logging and notifications.
+* Performs preservation services only when required.

data/docs/ll-example/files-dir/LLexample-tokeep.txt

@@ -0,0 +1,10 @@
+## Longleaf
+Longleaf is a command-line tool which allows users to configure a set of storage locations and define custom sets of preservation services to run on their contents. These services are executed in response to applicable preservation events issued by clients. Its primary goal is to provide tools to create a simple and customizable preservation environment.  
+
+Longleaf:
+
+* Offers a predictable command-line interface and integrates with standard command-line tools.
+* Offers configurable and customizable criteria based preservation workflows.
+* Provides a base set of tools and a framework for building extensions.
+* Provides activity logging and notifications.
+* Performs preservation services only when required.

data/docs/quickstart.md

@@ -0,0 +1,270 @@
+## Longleaf basic usage tutorial
+
+This tutorial provides an introduction to the basic functionality of Longleaf by demonstrating how to configure and execute a small set of preservation tasks, using an example data directory as a local sandbox on your own computer.
+
+**Longleaf basic usage tasks covered in this tutorial:**
+
+* Validate the mandatory Longleaf configuration file that contains the storage locations and preservation activities you will use
+* Register example data files
+* Validate metadata for registered files
+* Run a Preservation action on example data files
+* Alter an example data file to cause an error; catch the error by re-running the Preservation action
+* Re-register the altered file, and preserve the file in its new, altered state
+
+### System Requirements for this tutorial
+Longleaf scripts rely on common UNIX programs. In Mac OS X and Linux operating systems, these programs will likely already be installed, but some of these tools, such as `rsync` may be missing from a Windows system unless you have installed it.
+
+### Example data directory for this tutorial
+The example data directory for this tutorial is named 'll-example'; it is located in the 'docs' folder of the longleaf-preservation repository. 
+
+The 'll-example' directory contains all the materials required for completing this tutorial:
+
+* an example configuration file, 'config-example-relative.yml', that is pre-configured for tutorial tasks
+* a folder of example data files to be preserved
+* empty scaffolding folders that will be used for storing: 1) metadata files about the original data files, 2) the replicated data files created from the originals, and 3) metadata files about the replicated data files.
+
+**folder structure of 'll-example' directory: materials for tutorial tasks**  
+```tree
+└───ll-example
+    │   config-example-relative.yml
+    │
+    ├───files-dir
+    │       LLexample-PDF.pdf
+    │       LLexample-TOCHANGE.txt
+    │       LLexample-tokeep.txt
+    │
+    ├───metadata-dir
+    │
+    │
+    ├───replica-files
+    │
+    │
+    └───replica-metadata
+```
+
+Subdirectories in 'll-example' are used as follows:
+
+**'files-dir'**  
+Contains three example data files that will be preserved and replicated.
+
+**'metadata-dir'**  
+Empty at start of tutorial; metadata files about the data files in 'files-dir' will be stored and automatically updated in this directory during Register and Preserve actions.
+
+**'replica-files'**  
+Empty at start of tutorial; replicated data files (copies) created during Preserve actions run on the data files in 'files-dir' will be stored in this directory.
+
+**'replica-metadata'**  
+Empty at start of tutorial; metadata files about the replicated data files in 'replica-files' will be stored in this directory.
+
+### Set up your local sandbox: copy the example data directory to your Desktop
+Copy the 'll-example' directory to a location where it will be easy to access and work with. For example,it might be convenient to copy 'll-example' to your 'Desktop' location.
+
+Note: All paths in the commands in this tutorial are relative to the 'll-example' folder itself, so if you execute commands from within 'll-example,' you can use the paths as shown with no alterations.
+
+### Review the example Longleaf configuration file
+
+**Locations**  
+The example configuration file references storage locations based on the subdirectory names in 'll-example':
+
+* The 'data-directory' location points to 'files-dir' as the location of the original data files to be preserved, and 'metadata-dir' for storing metadata files created about these original data files.
+* The 'backup-directory' location refers to the 'replica-files' folder as the storage location where the copies of the original files will be stored, and 'replica-metadata' for metadata files.
+
+**Services**  
+The 'services' area in the configuration file defines characteristics of work scripts, such as the target storage location for the replication script, and the checksum algorithm for the fixity script.  
+
+**Service Mappings**  
+The 'service-mappings' area specifies which services will run at a particular storage location. In the example configuration file, for example, the services 'example_replication' and 'example_fixity' are assigned to run at location 'data-directory'. At location 'backup_directory', however, only 'example_fixity' is assigned to run, so files there will have fixity checks, but will not get replicated.  
+
+```yml
+locations: data-directory
+  services:
+    - example_replication
+    - example_fixity
+- locations: backup-directory
+  services:
+      - example_fixity
+```
+
+**Relative Paths in the Configuration File**  
+Storage locations in this configuration file specify paths relative to the location of the configuration file itself, and will also be evaluated relative to the location of the configuration file itself when Longleaf commands are run. In this tutorial, the configuration file is located inside 'll-example', at the same level as the data and metadata folders.  
+
+### Check that you can run Longleaf, by viewing the help text page
+Once you have copied the 'll-example' directory to an accessible working location, and have familiarized yourself with the configuration yaml file, you are ready to start using Longleaf!
+
+First confirm that you can run Longleaf, as you did in the ["Installation Instructions" page](install.md) of this site. Open a terminal window and `cd` into the 'll-example' directory,  then enter the command 'longleaf', with no arguments:    
+```
+longleaf
+```
+This command will output the help page text, showing all available commands.
+
+### Validate the example configuration file
+Next, you will validate the Longleaf configuration file, to ensure that storage locations and paths are correctly specified and accessible.
+
+As noted above, all paths in this tutorial are relative to the 'll-example' directory, so make sure that you execute commands from within that directory, or amend paths accordingly.
+
+Command for validating configuration file:
+
+```
+longleaf validate_config -c config-example-relative.yml
+```
+
+Successful validation of the configuration file outputs the following message in terminal:
+```
+SUCCESS: Application configuration passed validation: config-example-relative.yml
+```
+
+### Register example data files
+Once the configuration file has been validated, you can proceed to registering the example data files, so that they are ready for further preservation actions with Longleaf.
+
+Note that Longleaf commands can be run on directories, or individual files. For example, when using the Register command, you can either:  
+
+1. register a whole directory at once, which will individually register every file in that directory   
+**or**
+2. register individual files.
+
+In this example of using the Register command, we will register an entire directory of files by specifying the directory path.
+
+Use command:   
+```
+longleaf register -c config-example-relative.yml -f files-dir
+```
+If files successfully registered, Longleaf will list the registration outcome for each file within the directory:
+```
+SUCCESS register /data/ll-example/files-dir/LLexample-PDF.pdf
+SUCCESS register /data/ll-example/files-dir/LLexample-TOCHANGE.txt
+SUCCESS register /data/ll-example/files-dir/LLexample-tokeep.txt
+
+```
+
+### Validate the new metadata files
+Validate the metadata files that were created for the files you just registered.
+Use command:     
+```
+longleaf validate_metadata -c config-example-relative.yml -f files-dir
+```
+Confirmation of validation for the metadata files:
+```
+SUCCESS: Metadata for file passed validation: /data/ll-example/files-dir/LLexample-PDF.pdf
+SUCCESS: Metadata for file passed validation: /data/ll-example/files-dir/LLexample-TOCHANGE.txt
+SUCCESS: Metadata for file passed validation: /data/ll-example/files-dir/LLexample-tokeep.txt
+
+```
+
+
+### Run the Preserve command, to replicate and check fixity on the registered files.
+Use command:   
+```
+longleaf preserve -c config-example-relative.yml -f files-dir
+```
+Confirmation of successful Preservation action completed on all files in the files-dir directory:
+```
+SUCCESS register /data/ll-example/replica-files/LLexample-PDF.pdf
+SUCCESS preserve[example_replication] /data/ll-example/files-dir/LLexample-PDF.pdf
+SUCCESS preserve[example_fixity] /data/ll-example/files-dir/LLexample-PDF.pdf
+SUCCESS register /data/ll-example/replica-files/LLexample-TOCHANGE.txt
+SUCCESS preserve[example_replication] /data/ll-example/files-dir/LLexample-TOCHANGE.txt
+SUCCESS preserve[example_fixity] /data/ll-example/files-dir/LLexample-TOCHANGE.txt
+SUCCESS register /data/ll-example/replica-files/LLexample-tokeep.txt
+SUCCESS preserve[example_replication] /data/ll-example/files-dir/LLexample-tokeep.txt
+SUCCESS preserve[example_fixity] /data/ll-example/files-dir/LLexample-tokeep.txt
+
+```
+
+### Look at the output of the Preserve command
+Take a look at the SUCCESS output messages from the `preserve` command above.
+
+Notice that for each file included in the Preservation action, Longleaf indicates "SUCCESS" for the "register" and "preserve" components of the Preservation action, as well as the individual scripts within the "preserve" component.
+
+Also take a look inside the subfolders in your 'll-example' sandbox folder, using Finder or command-line tools.
+
+You'll notice that there are newly-created data files and metadata files in the 'replica-' directories. The original data files from 'files-dir' have been copied to the 'replica-files' directory, and metadata files for those copies have been created in the 'replica-metadata' directory.
+
+![preserve files folders output](img/ll-example-preserved.png)
+
+### Re-run the Preserve command, to check the integrity of the files that are being preserved.
+
+Since the 'example_fixity' script in our example configuration file is set to frequency: 30 seconds, we can check fixity on the preserved files once 30 seconds have elapsed since the last preservation action.
+
+Use command:   
+```
+longleaf preserve -c config-example-relative.yml -f files-dir
+```
+Success output message:
+```
+SUCCESS preserve[example_fixity] /data/ll-example/files-dir/LLexample-PDF.pdf
+SUCCESS preserve[example_fixity] /data/ll-example/files-dir/LLexample-TOCHANGE.txt
+SUCCESS preserve[example_fixity] /data/ll-example/files-dir/LLexample-tokeep.txt
+
+```
+Note that the output in terminal window is much shorter than the first `preserve` command. This output only shows "SUCCESS" and preserve[example_fixity] for each file. This time register and replication are not included because those actions already ran, and do not need to run this time. Only fixity checks ran in this Preserve action.
+
+In the finder window, notice that the Date Modified is updated on the metadata files in the metadata-dir. The metadata files for the original data files are updated to reflect these Preservation actions running.
+
+### Cause a change to a file, and catch the change with the Preservation command.
+Now make a change to one of the files that is being preserved, which you will then catch by re-running `preserve` on the storage directory for that file.
+
+Open up the file: 'll-example/files-dir/LLexample-TOCHANGE.txt'. On line 4 of the text file, you'll see "( insert changed text    ) ". Insert your cursor near this line, and type something to make a change to the file. Then save the file and close it. In your 'll-example/files-dir' directory, notice that the Date Modified has changed for this file.
+
+Run the `preserve` command again. This time it will fail, because one of the files under preservation has been altered since the file's last checksums were recorded.   
+
+Use command:   
+```
+longleaf preserve -c config-example-relative.yml -f files-dir
+```
+Output showing failed fixity check on the file 'll-example/files-dir/LLexample-TOCHANGE.txt':
+```
+SUCCESS preserve[example_fixity] /data/ll-example/files-dir/LLexample-PDF.pdf
+FAILURE preserve[example_fixity] /data/ll-example/files-dir/LLexample-TOCHANGE.txt: Fixity check using algorithm 'sha1' failed for file /data/ll-example/files-dir/LLexample-TOCHANGE.txt: expected 'effa1bfc1b93f1260a36044bcd668240cf14738a', calculated 'cd5e53f6945ceda2d90b003a39af509d7acb068f.'
+SUCCESS preserve[example_fixity] /data/ll-example/files-dir/LLexample-tokeep.txt
+
+```
+
+### Re-register the altered file.
+Now you will re-register the altered file, using the `--force` option for the `register` command. Run this registration command at the file level so that only this file is re-registered, not the entire directory.
+
+Re-registration will update the file's preservation metadata to the new state of 'LLexample-TOCHANGE.txt'.
+
+Note, however, that the re-registered altered file (ll-example/files-dir/LLexample-TOCHANGE.txt) will still not match the copy of LLexample-TOCHANGE.txt that is stored in "replica-files" (ll-example/replica-files/LLexample-TOCHANGE.txt), because the replica copy was created earlier, from the unaltered original file.
+
+Use command:   
+```
+longleaf register -c config-example-relative.yml -f files-dir/LLexample-TOCHANGE.txt --force
+```
+Success output message:
+```
+SUCCESS register /data/ll-example/files-dir/LLexample-TOCHANGE.txt
+```
+
+### Run Preserve on the re-registered file.
+Running `preserve` on the re-registered altered file will replicate the new state of this file to the copied data location. As with `register --force`, run `preserve` at the file level, not the directory.
+
+Use command:   
+```
+longleaf preserve -c config-example-relative.yml -f files-dir/LLexample-TOCHANGE.txt
+```
+
+The terminal output shows the new registration of the file, and the replication and fixity scripts running on this file.
+In finder, you can see that the Date Modified of the 'll-example-TOCHANGE.txt' file in the 'replica-files' directory now matches the original file. Open up 'replica-files/ll-example-TOCHANGE.txt' and you'll see the added line of text in this file.
+
+Successful preservation of re-registered changed file:
+```
+SUCCESS register /data/ll-example/replica-files/LLexample-TOCHANGE.txt
+SUCCESS preserve[example_replication] /data/ll-example/files-dir/LLexample-TOCHANGE.txt
+SUCCESS preserve[example_fixity] /data/ll-example/files-dir/LLexample-TOCHANGE.txt
+
+```
+
+### Re-run Preserve at the directory level to check all three files.
+After the 30-sec fixity check interval has elapsed, re-run the `preserve` command at the directory level as before, and now all three files pass again.
+
+Use command:   
+```
+longleaf preserve -c config-example-relative.yml -f files-dir
+```
+Success output message:
+```
+SUCCESS preserve[example_fixity] /data/ll-example/files-dir/LLexample-PDF.pdf
+SUCCESS preserve[example_fixity] /data/ll-example/files-dir/LLexample-TOCHANGE.txt
+SUCCESS preserve[example_fixity] /data/ll-example/files-dir/LLexample-tokeep.txt
+
+```