The backstop command

The backstop command is a UNIX, Linux, and *BSD tool. Intuitively, backstop fills in the missing objects or holes that exist in the target directory relative to the source directories thereby creating a merged view of the target and source directories. De-backstop undoes this. See "backstop -m" for a manual page or the homepage for more information.

The command backstop was created over twenty years ago to manage development environement toolchains in which part of the project was under source control and part of the project was not, e.g. binaries. It was inspired by lndir, graft, and "Source Control to Project Control: Applying RCS and SCCS" by Don Bolinger and Tan Bronson. Techniques have changed with time, but backstop is a robust tool with an extensive test suite that runs around 2700 tests, a combination of HUnit, QuickCheck, and black box tests.

In the author's obviously biased veiw, backstop has pedagogical value. The module Backstop uses a ReaderT monad transformer to manage an Environment passed to it via the command line, a StateT monad transformer to keep track of a set of counters and to keep track of the status of direcotry content while backstopping or de-backstopping. The last two are Monoids. With this structure, the handling of a dry-run for backstop or de-backstop is rather powerful even it is a bit subtle (obscure) to understand.

On a personal note, the author truly began to appreciate Haskell after creating the Backstop module and its test suite and has not stopped appreciating Haskell since.

The backstop manual page

NAME
   backstop - Backstop a target directory by source directories

SYNOPSIS
   backstop [-nprt] [-a|-d] trgdir srcdir [srcdir ...]
   backstop -h
   backstop -l
   backstop -m
   backstop -v
   backstop -y

AVAILABILITY
   Marcus D. Gabriel (c)1999-2019.  All rights reserved.

   marcus@gabriel.name

   License terms: GNU GPL version 3 or later (backstop -l)

DESCRIPTION
   Backstop a target directory by source directories thereby
   creating a backing chain using relative symbolic links by default
   or absolute symbolic links by option.  If more than one source
   directory is given, backstop the target directory with each
   source directory in turn starting from left to right on the
   command line.

   Intuitively, backstop fills in the missing objects or holes that
   exist in the target directory relative to the source directories
   thereby creating a merged view of the target and source
   directories.

   De-backstop a target directory by its source directories.  In
   this case, the source directories no longer need to exist.  If
   more than one source directory is given, de-backstop the target
   directory by the source directories.

   Symbolic links are never followed.  However, the target and
   source directories are canonicalized (realpath(3)) internally by
   the command backstop before backstopping and de-backstoppoing.

   By default no output is displayed except possibly to STDERR.

ALGORITHM
   There must be at least two arguments or operands.  The first
   operand is the target directory, and the second operand and
   beyond are source directories.  The target and source directory
   must be parallel directories, that is, neither canonicalized
   (realpath(3)) directory path may be a sub-directory of the other.
   If the above is not true, a usage error occurs.

   Nevertheless, pathnames are internally in reduced form such that
   symbolic link names are treated literally when finding directory
   names.  See "cd -L" of ksh(1).  In other words, components in the
   pathname that are not directories but symbolic links to
   directories are not resolved to their corresponding directories.

   A list of objects or names is collected under the root of the
   source directory excluding the directory dot (.) and the
   directory double-dot (..).  If the list is empty, the algorithm
   is done, otherwise the objects divide into two classes, objects
   that are not directories and objects that are directories.  There
   are five possibilities:

   1. The object is either dot (.) or double-dot (..) whereupon no
      action is taken.

   2. If an object of the same name as the name of the object under
      the root of the source directory does not exists under the
      root of the target directory, then a symbolic link, relative
      or absolute as required, is created under the root of the
      target directory to the object under the root of the source
      directory.  If populating (-p) and the object under the root
      of the source directory is a directory, then a sub-directory
      is created instead.

   3. If an object of the same name as the name of the object under
      the root of the source directory does exists under the root of
      the target directory and is a file, no action is taken,
      regardless of whether or not the object under the root of the
      source directory is a file or a directory.

   4. If an object of the same name as the name of the object under
      the root of the source directory does exists under the root of
      the target directory and is a directory, and if the object of
      the same name under the root of the source directory is a
      file, no action is taken.

   5. If an object of the same name as the name of the object under
      the root of the source directory does exists under the root of
      the target directory and is a directory, and if the object of
      the same name under the root of the source directory is also a
      directory, then recursion occurs with the objects of the same
      name under the roots of the target and source directories as
      new root target and source directories, respectively.

   When de-backstopping a target directory by source directories,
   the sources no longer need to exist.  Symbolic links under the
   target are removed if and only if they point to a pahtname under
   one of the source directories.  This can be determined even if
   the source directory no longer exists because symbolic links
   within directory pathnames are taken literally.  See "cd -L" of
   ksh(1).

   When de-populating while de-backstopping (-pd), a directory is
   removed if all objects within the directory are symbolic links
   that have been remove while de-backstopping.  An empty directory
   is removed if and only if there exists a corresponding directory
   path under one of the source directories as under the target
   directory.  This can only be determined if the source directory
   and correponding sub-directory still exist.  If not, then no
   action is taken.

OPTIONS
   The following options are supported:

   -a Create symbolic links which are absolute paths.

   -d De-backstop the target directory by its source directories.
      The -a option has no affect on the -d option.

   -h Display a short command summary.

   -l Display the backstop license terms.

   -m Display this internal manual page.

   -n Take no action but trace possible program execution.  The -n
      option implies the -t option.

   -p Populate the target by making equivalent sub-directories of
      the source sub-directories instead of symbolic links for these
      sub-directories that point back into the sources.  For
      example, if the target directory is empty, then for a set of
      source directories, from left to right on the command line,
      this creates a combined directory structure of the sources
      under the target directory in which all non-directories are
      symbolic links pointing back into the source directories.
      This is similar to the lndir(1) command of the X consortium.

      With the -d option, all sub-directories emptied of symbolic
      links under the target directory are removed, and all empty
      directories are removed if and only if the correspoding
      sub-directory under the source directory exists.

   -r Report the number of symbolic links and directories created,
      the number of calls and maximum depth of backstop, the
      maximum breadth observed by backstop, and the number of non-
      fatal errors encountered.  With the -d option, show the
      number of symbolic links and directories removed.

   -t Show the trace of program execution.  The output is a list
      of executable commands.

   -v The version of backstop.

   -y A synopsis of the internal manual page.

OPERANDS
   trgdir
      The directory that will be backed by other directories.  The
      target directory can be backed by multiple source directories
      where each source directory could be backed by yet another
      directory or multiple directories thereby creating an
      extensible backing chain.

   srcdir
      The directory which backs a target directory.  The source
      directory can be backed by multiple additional directories
      where each additional directory could be backed by yet another
      directory or multiple directories thereby creating an
      extensible backing chain.

USAGE NOTES
   Evolved with ghc 6.10, 6.12, 7.0, 7.4, 7.10, 8.0.2, and 8.4.1.
   Tested with 8.4.1.

EXAMPLES
   To display a summary of usage, use

      backstop -h

   To display a synopsis of this internal manual page, use

      backstop -y

   To display this internal manual page, use

      backstop -m

   To trace program execution, use

      backstop -t /export/install/sparc/devlopment/modules \
                  /export/install/sparc/modules

   To trace program execution taking no action, use

      backstop -n /export/install/sparc/devlopment/modules \
                  /export/install/sparc/modules

   To back /export/install/sparc/devlopment/modules with
   /export/install/sparc/modules using relative symbolic links, use

      backstop /export/install/sparc/devlopment/modules \
               /export/install/sparc/modules

   To back /export/install/sparc/devlopment/modules with
   /export/install/sparc/modules using absolute symbolic links, use

      backstop -a /export/install/sparc/devlopment/modules \
                  /export/install/sparc/modules

   To stop backing /export/install/sparc/devlopment/modules with
   /export/install/sparc/modules, use

      backstop -d /export/install/sparc/devlopment/modules \
                  /export/install/sparc/modules

ENVIRONMENT VARIABLES
   PAGER   Page the internal manual page or license terms
           using "${PAGER}", otherwise print it.

EXIT STATUS
   An exit status of 0 is returned if successful, otherwise non-zero
   is returned.  The following error exit codes are used by
   backstop:

       EXIT CODE    MEANING
          251       Less than two operands.
          252       Not a directory, that is, trgdir or one or more
                    of the srcdir are not a directory.
          253       Not parallel directories, that is, a srcdir is
                    a sub-directory of trgdir or vice versa, or one
                    of the srcdir is a sub-directory of another
                    srcdir.
          254       Not yet implemented.
          255       Non-fatal errors occurred.  Error messages are
                    sent to STDERR for each non-fatal error that
                    occurred with return code equal to the number of
                    non-falal errors if less than 251, otherwise the
                    return code is 255, that is, "infinity".

FILES
   N/A.

SEE ALSO
   ln(1), mkdir(1), rm(1), rmdir(1), ksh(1), lndir(1), realpath(3)

   "Source Control to Project Control: Applying RCS and SCCS" by Don
   Bolinger and Tan Bronson. ISBN 1-56592-117-8.

NOTES
   Please send bug reports to https://github.com/mdgabriel/backstop/issues.

BUGS
   No known bugs to date.