Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
XSHAR(1)		     WebJob Documentation		      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	(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

   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.

perl v5.24.1			  2017-04-30			      XSHAR(1)

NAME | SYNOPSIS | DESCRIPTION | MODES OF OPERATION (SHELL ARCHIVE) | OPTIONS (XSHAR) | OPTIONS (SHELL ARCHIVE) | FOLLOW-UP COMMAND (SHELL ARCHIVE) | EXAMPLES (SHELL ARCHIVE) | EXAMPLES (XSHAR) | AUTHOR | HISTORY | SEE ALSO | LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=xshar&sektion=1&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help