dsi.man.txt #4

USAGE for dsi v1.3.2:

Usage varies based on mode, which can be one of: create, diff, info, list, rm, rmall, tags

dsi create [<tag>]

dsi diff [<tag>[@<rev>]]

dsi info

dsi list [<tag>]

dsi rm [<tag>@<rev>]

dsi rmall [<tag>]

dsi tags

Key environment variables:

* DSI_TAG defines a default for <tag>.
* DSI_STORAGE, or specify as '-s <storage_dir>'.
* DSI_IMAGE_ROOT, defaults to $PWD, or specify as '-d <image_root>'.

or

dsi [-h|-man|-V]


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

	Detection of changes includes:
	* Last-modified Timestamp
	* Newly added files/directories
	* Deleted files/directories
	* Changes to contents of files, including showing diffs
	* 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.

TAGS AND REVISIONS:
	A DSI is assigned a tag on creation, which is generally the name of the
	product and optionally product version ID, e.g. 'fgs' or 'fgs-1.0'.

	DSI tag names can include alphanumeric characters, dashes, underscores,
	and dots.

	DSI revisions are positive integers associated with a tag and assigned
	upon creation.

MODES:
 Create, specified with 'create [<tag>]' (or 'c' for short)
	Create and store a DSI image with a given tag name.

 Diff, specified with 'diff [<tag>]' (or 'd' for short)
	Diff a DSI image with the given tag, using the latest version or a specified
   revision tag.  Optionally, specify the @<rev> to compare against a revision
   other than the head revision.

   If no flags are specified to limit the output, a comprehensive diff will
   report:
   * Timestamp differences
   * Checksum differences
   * Size Differences

   The Diff mode supports flags to exlcude certain things from comparison:

 Fix, specified with 'fix [<tag>]' (or 'f' for short)
	Fix a directory structure as it appears on disk, focing it to match
	the image. This will overwrite files in the target structure.

 Info, specified with 'info' (or 'i' for short)
	Show DSI environment variables, default settings, and version info.

 List, specified as 'list [<tag>]' (or 'l' for short)
	List stored DSI images for the given tag.

 Remove, specified as 'rm [<tag>]@<rev>'
	Remove the specified revision for the given tag.  For this usage
	the revision must be specified.

 RemoveAll, specified as 'rmall <tag>'
	Remove all images for the given tag.

 Tags, specify as 'tags' (or 't' for short)
	List available image tags.

<tag>[@<rev>]
	Specify the DSI tag and revision.  A default tag value can be defined by
	setting the DSI_TAG environment variable.

	For Diff mode, the following can be specified:
	<tag>          Explicit value for <tag>, overriding DSI_TAG.
                       Revision defaults to @LATEST

	<tag>@<rev>    Explicit definition of tag and revision

	@<rev>         Uses DSI_TAG for the tag, with explicit rev.

        For Create or List modes, the following can be specified:
	<tag>          Explicit value for <tag>, overriding DSI_TAG.
	               Revision is not set with Create and List modes.

	For Remove mode the tag may be implied (with DSI_TAG) or specified
	explicitly.  The revision is required.

	For RemoveAll mode the tag must be specified explicitly.  A revision
	is not allowed.

OPTIONS:
 -r <image_root>
	Specify the root directory in which to create a DSI, or in which to
	do a comparsion against stored DSIs. The default is the current
	working directory as indicated by $PWD.

 -s <storage_dir>
	Specify the DSI storage dir. A default can be defined by setting
	the DSI_STORAGE environment variable

GENERAL OPTIONS:

 -L <log>
	Specify the path to a log file to enable logging.  Or, specify
	'-L on' to enable logging using a default log file name:
	/tmp/dsi.v1.3.2.<datestamp>.log

	By default, logging is disabled.

	NOTE: This script is self-logging if logging is enabled. That is,
	output displayed on the screen is simultaneously captured in the log
	file.  Do not run this script with redirection operators like '> log'
	or '2>&1', and do not use 'tee.'

 -si	Operate silently.  All output (stdout and stderr) is redirected to the
	log only; no output appears on the terminal.  This cannot be used with
	'-L off'.

 -D     Set extreme debugging verbosity.

HELP OPTIONS:
 -h	Display short help message
 -man	Display man-style help message
 -V	Dispay version info for this script and its libraries.

DSI FILE FORMAT:
	The directory structure image file format is defined in the
	documentation.

FILES:
	DSI package definition files are stored in the DSI_STORAGE directory,
	and have a .dsi file name suffix.

EXAMPLES:
	Example 1: Create a DSI of /p4/common
	dsi c -r /p4/common