= Directory Structure Image (DSI) C. Thomas Tyler :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. == Command Line Usage Run the `dsi` tool with the `-man` flag to display a synopsis of options, plus documentation of commands and options, examples, and other info. Using the `-h` flag will display only the synopsis of options. [source] .Command Line Usage ---- include::gen/dsi.man.txt[] ---- == Image File Format and Samples === Image File Format Following is the image file format: .Image File Format ---- include::image_format.txt[] ---- === Sample Image Files Sample 1: Friendly Greeting System (FGS) Sample image file: # Sample Friendly Greeting System file format, with tag 'fgs': i fgs 2020.1 r20.1 26937 Friendly Greeting System d src unset:unset 750 20201123080422 f src/hello.h unset:unset 640 20201123080422 f src/hello.c unset:unset 640 f src/Makefile unset:unset 640 f src/build.sh unset:unset 750 Sample 2: FGS with sparse files.