XSHAR(1)

NAME
xshar - Create an extended shell archive of one or more files.

SYNOPSIS
xshar [-u umask] file [file ...]

DESCRIPTION
This utility creates an extended shell archive from one or more input files. The archive is written to stdout as a sh(1) script. Only regular, text files may be placed in the archive. The resulting script will attempt to create intermediate directories on extraction.

Archives, when executed with no arguments, will print the following usage:

  <script> {-d|--deploy} [options] [-- command [options]]
           {-l|--lsshar} [options] [-- command [options]]
           {-r|--remove} [options] [-- command [options]]
           {-R|--revert} [options] [-- command [options]]

Details about the archive's various execution modes and options can be found in the following sections.

MODES OF OPERATION (SHELL ARCHIVE)
Each of the shell archive's execution modes is described below.

-d|--deploy
    Deploy the contents of the archive (creating intermediate directories as needed), and conditionally execute a follow-up command.

-l|--lsshar
    List the contents of the archive, and conditionally execute a follow-up command.

-r|--remove
    Remove the contents of the archive (including empty directories), and conditionally execute a follow-up command.

-R|--revert
    Revert the contents of the archive, and conditionally execute a follow-up command. Note that only files with a corresponding backup file (<file>.xsb) will be reverted.

OPTIONS (XSHAR)

-u umask
    Specifies a umask value to embed (as a default value) in the shell archive. If not specified, a value of 022 is used.

OPTIONS (SHELL ARCHIVE)
Each of the shell archive's execution modes will accept the following options:

-C dir
    Change to the specified directory before performing any work. If the directory does not exist, the script will abort.

-u umask
    Set the run-time umask to the value specified.

Additionally, --deploy mode will accept the following option:

-b  Create backup files if the files being deployed already exist. Backup files will have an extension of '.xsb'.

FOLLOW-UP COMMAND (SHELL ARCHIVE)
The tokens described below may be used as place holders in the follow-up command. Before the command is executed, these tokens are expanded to their current values. The character '%' may be used to produce a literal token. For example, '%%1' would be expanded to '%1'.

%%  Escapes a single '%' character.

%1-%N
    Expands to the name of a file or directory contained in the archive. The order that files are added to the archive determines their token value.

%contents
    Expands to a list of all files and directories in the archive.

%cmd
    Expands to the basename of the executing script.

%cwd
    Expands to the current working directory. In general, this will differ from %owd when the -C option is used to change to directories.

%dirs
    Expands to a list of all directories in the archive.

%files
    Expands to a list of all files in the archive.

%owd
    Expands to the original working directory.

EXAMPLES (SHELL ARCHIVE)

  Example 1. List the contents of a shell archive
This example demonstrates how to list the contents of an archive called 'out.sh'.

  $ sh out.sh --lsshar

or (in short form)

  $ sh out.sh -l

  Example 2. Deploy the contents of a shell archive
This example demonstrates how to deploy the contents of an archive called 'out.sh' to /usr/local/etc.

  $ sh out.sh --deploy -C /usr/local/etc

or (in short form)

  $ sh out.sh -d -C /usr/local/etc

Note: All files in an archive are relative. Therefore, if the -C option is not used, the files will be extracted to the current working directory.

Note: The specified directory must exist, or the script will abort.

  Example 3. Remove the contents of a shell archive
This example demonstrates how to remove the contents of an archive called 'out.sh' from /usr/local/etc.

  $ sh out.sh --remove -C /usr/local/etc

or (in short form)

  $ sh out.sh -r -C /usr/local/etc

Note: All files in an archive are relative. Therefore, if the -C option is not used, the files will be removed from the current working directory.

Note: The script will attempt to remove any directories that it may have created. These operations will fail if the directories are not empty.

  Example 4. Use tokens in a follow-up command
This example demonstrates how to use tokens in a follow-up command to perform inline editing of a file (stdout.cfg) once it has been deployed. First, list the contents of the archive (out.sh):

  $ sh out.sh -l
  lsshar - config (%1)
  lsshar - config/import.cfg (%2)
  lsshar - config/stdout.cfg (%3)
  lsshar - config/upload.cfg (%4)

Note the token value (%3) that correspnds to the file stdout.cfg.

Next, deploy the contents of the archive to the current working directory using a follow-up command that will remove any lines in stdout.cfg that begin with the string 'Import='.

  $ sh out.sh -d -- 'perl -n -i -e "print unless (/^Import=/);" %3'
  deploy - config
  deploy - config/import.cfg
  deploy - config/stdout.cfg
  deploy - config/upload.cfg
  runcmd - perl -n -i -e "print unless (/^Import=/);" config/stdout.cfg
  status - 0

  Example 5. Deploy a shell archive containing a uuencoded binary
This example demonstrates how to deploy a shell archive containing a uuencoded file and set the permissions on the resulting binary. Assume that the archive in question was built using Example 3 from the EXAMPLES (XSHAR) section.

  $ sh webjob.sh -d -- 'uudecode %1 && chmod 755 `basename %1 .uu`'

To remove the original uuencoded file when done, substitute the command shown above with the one given here:

  '{ uudecode %1 && chmod 755 `basename %1 .uu` ; rm -f %1 ; }'

EXAMPLES (XSHAR)

  Example 1. Create a shell archive of several '.cfg' files
This example demonstrates how to create an archive of all '.cfg' files in the current directory:

  $ xshar *.cfg > out.sh

  Example 2. Create a shell archive of a given directory
This example demonstrates how to create an archive of all files in a given directory:

  $ xshar `find <dir> -type f` > out.sh

  Example 3. Create a shell archive containing a uuencoded binary
This example demonstrates how to create a shell archive containing a uuencoded binary.

  $ uuencode webjob > webjob.uu
  $ xshar webjob.uu > webjob.sh

AUTHOR
Klayton Monroe

HISTORY
This utility started out as a script that could create custom shell archives to hold WebJob config files. The shell archive format is a good fit for WebJob because it is executable and can hold multiple files. Therefore, clients needing to update their local configuration can do so in a single operation simply by running a job that downloads and deploys their personalized shell archive.

Over time, the custom bits that made this utility application-specific were refactored and generalized away. Also, the code was heavily influenced by PaD, which predates the use of shell archives within the project. In particular, xshar adopted PaD's delivery command capability -- being able to run delivery/follow-up commands has proven to be very useful in WebJob deployments.

This utility first appeared in WebJob 1.8.0.

SEE ALSO
sh(1), shar(1)

LICENSE
All documentation and code are distributed under same terms and conditions as WebJob.