xshar - Create an extended shell archive of one or more files.
xshar [-u umask] file [file ...]
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.
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.
- -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.
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'.
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.
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
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.
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.
This example demonstrates how to use tokens in a follow-up command to
perform inline editing of a file (upload.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/upload.cfg (%3)
Note the token value (%3) that correspnds to the file upload.cfg.
Next, deploy the contents of the archive to the current working
directory using a follow-up command that will remove any lines in
upload.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/upload.cfg
runcmd - perl -n -i -e "print unless (/^Import=/);" config/upload.cfg
status - 0
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 ; }'
This example demonstrates how to create an archive of all '.cfg' files
in the current directory:
$ xshar *.cfg > out.sh
This example demonstrates how to create an archive of all files in a
given directory:
$ xshar `find <dir> -type f` > out.sh
This example demonstrates how to create a shell archive containing a
uuencoded binary.
$ uuencode webjob > webjob.uu
$ xshar webjob.uu > webjob.sh
Klayton Monroe
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.
sh(1), shar(1)
All documentation and code are distributed under same terms and
conditions as WebJob.
|
