= Directory Structure Image (DSI)
C. Thomas Tyler <cttyler@gmail.com>
:revnumber: v2021.1
:revdate: 2020-01-02
:doctype: book
:icons: font
:toc:
:toclevels: 5
:sectnumlevels: 4
:xrefstyle: full
// Attribute for ifdef usage
:unix_doc: true

== Preface

:sectnums:

== Introduction

Directory Structure Image (DSI) is a comprehensive comparison utility, used primarily to detect changes to a directory tree since  initial installation.  An image can be generated as part of the release process for a software product, and used subsequently to detect changes.

== Overview

The image identifies _elements_ which can be files, directories, or symlinks. Elements may be specified as absolute paths or paths relative to a variable installation root.  In addition to files in an install root, additional elements may be specified that may be scattered sparsely across a filesystem.

Directories can be _strictly_ or _loosely_ controlled. A strictly controlled directory tree is one in which the image comprehends all elements in the tree, and excess or missing files are unexpected. A loosely controlled direcotry is one in which the image specifies specific files, but allows for excess elementsk

The DSI can be configured to understand a product that may include sparsely deployed files throughout a filesystem.

Detection of changes includes:

* Newly added files/directories/symlinks.
* Deleted files/directories/symlinks.
* Differing last-modified timestamp of existing elements.
* List files with differing content.
* Changes in file/directory owner.
* Changes in file/directory group.
* Changes in file/directory permissions (e.g. +x bit, etc.)

Command line flags can suppress certain types of diffs that may not be important in certain scenarios, such as group/owner changes, as well as special verifications such as "owner can be anything except root."

This software is powered by the Perforce Helix version management software using Helix native DVCS features to show file and content differences.
