In the first form, the file list is given as command arguments. In the
second form, the file list is read from standard input. The resulting
archive is sent to standard output unless the -o option is given.
Options can be given in any order. Some options depend on each other:
the -o option is required if the -l or -L option
is used. The -n option is required if the -a option
is used. Also see -V below.
Some options are special purpose:
--help
Print a help summary on standard output, then immediately exits.
--version
Print the version number of the program on standard output, then
immediately exits.
-q
--quiet
Verbose off at shar time. Messages are usually issued
on standard error to let the user follow the progress, while making
the archives. This option inhibits these messages.
Allow positional parameter options. The options -M, -B,
-T, -z and -Z may be embedded, and files to
the right of the option will be processed in the specified mode.
Without the -p option, embedded options would be interpreted
as file names. See section Selecting how files are stocked for more information on these options.
-S
--stdin-file-list
Read list of files to be packed from the standard input rather
than from the command line. Input must be one file name per line.
This switch is especially useful when the command line will not hold
the list of files to be packed. For example:
find . -type f -print | shar -S -o /tmp/big.shar
If -p is specified on the command line, then the options
-M, -B, -T, -z and -Z may be
included in the standard input (on a line separate from file names).
The maximum number of lines of standard input, file names and options,
may not exceed 1024.
Save the archive to files `prefix.01' through
`prefix.nnn' instead of standard output. This option
must be used when the -l or the -L switches
are used.
When prefix contains any `%' character, prefix is then
interpreted as a sprintf format, which should be able to display
a single decimal number. When prefix does not contain such a
`%' character, the string `.%02d' is internally appended.
-l size
--whole-size-limit=size
Limit the output file size to size times 1024 bytes but don't
split input files. This allows the recipient of the shell archives
to unpack them in any order.
-L size
--split-size-limit=size
Limit output file size to size times 1024 bytes and split files
if necessary. The archives created with this option must be unpacked
in the correct order. If the recipient of the shell archives wants to
put all of them in a single folder, she shall save them in the correct
order for unshar, used with option -e, to unpack them
all at once. See section Invoking the unshar program.
For people used to saving all the shell archives into a single mail
folder, care must be taken to save them in the appropriate order.
For those having the appropriate tools (like Masanobu Umeda's
rmailsort package for GNU Emacs), shell archives can be saved
in any order, then sorted by increasing date (or send time) before
massive unpacking.
Name of archive to be included in the header of the shar files.
Also see the -a switch further down.
-s address
--submitter=address
The -s option allows for overriding the email address for the
submitter, for when the default is not appropriate. The automatically
determined address looks like `username@hostname'.
-a
--net-headers
Allows automatic generation of headers:
Submitted-by: address
Archive-name: name/partnn
The name must be given with the -n switch. If name
includes a `/', then `/part' isn't used. Thus
`-n xyzzy' produces:
xyzzy/part01
xyzzy/part02
while `-n xyzzy/patch' produces:
xyzzy/patch01
xyzzy/patch02
and `-n xyzzy/patch01.' produces:
xyzzy/patch01.01
xyzzy/patch01.02
-c
--cut-mark
Start the shar with a cut line. A line saying `Cut here' is
placed at the start of each output file.
Treat all files as text, regardless of their contents.
-B
--uuencode
Treat all files as binary, use uuencode prior to packing. This
increases the size of the archive. The recipient must have
uudecode in order to unpack.
Use of uuencode is not appreciated by many on the net, because
people like to readily see, by mere inspection of a shell archive,
what it is about.
-M
--mixed-uuencode
Mixed mode. Automatically determine if the files are text or binary
and archive correctly. Files found to be binary are uuencoded prior
to packing. This option is selected by default.
For a file is considered to be a text file, instead of a binary file,
all the following should be true simultaneously:
The file does not contain any ASCII control character besides BS
(backspace), HT (horizontal tab), LF (new line) or FF
(form feed).
The file does not contains a DEL (delete).
The file contains no character with its eighth-bit set.
The file, unless totally empty, terminates with a LF (newline).
No line in the file contains more than 200 characters. For counting
purpose, lines are separated by a LF (newline).
-z
--gzip
Use gzip and uuencode on all files prior to packing.
The recipient must have uudecode and gzip (used with
-d) in order to unpack.
Usage of -z in net shars will cause you to be flamed off
the earth.
-g level
--level-for-gzip=level
When doing compression, use -level as a parameter to
gzip. The -g option turns on the -z option
by default. The default value is 9, that is, maximum compression.
-Z
--compress
Use compress and uuencode on all files prior to packing.
The recipient must have uudecode and compress (used
with -d) in order to unpack. Option -C is a synonymous
for -Z, but is deprecated.
Usage of -Z in net shars will cause you to be flamed off
the earth.
-b bits
--bits-per-code=bits
When doing compression, use -bx as a parameter to
compress. The -B option turns on the -Z
option by default. The default value is 12, foreseeing the memory
limitations of some compress programs on smallish systems, at
unshar time.
Transmission of shell archives is not always free of errors. So one
should make consistency checks on the receiving site. A very simple
(and unreliable) method is running the UNIX wc tool on the output
file. This can report the number of characters in the file.
As one can guess this does not catch all errors. Especially changing of
a character value does not change the computed check sum. To achieve
this goal better method were invented and standardized. One very strong
is MD5 (MD = message digests). This is standardized in RFC 1321. The
produced shell scripts do not force the md5sum program to be
installed on the system. This is necessary because it is not yet part
of every UNIX. The program is however not necessary for producing the
shell archive.
-w
--no-character-count
Do not check with `wc -c' after unpack. The default is
to check.
-D
--no-md5-digest
Do not check with `md5sum' after unpack. The default is
to check.
-F
--force-prefix
Prepend the prefix character to every line even if not required.
This option may slightly increase the size of the archive, especially
if -B or -Z is used. Normally, the prefix character
is `X'. If the parameter to the -d option starts with
`X', then the prefix character becomes `Y'.
-d string
--here-delimiter=string
Use string to delimit the files in the shar instead of
`SHAR_EOF'. This is for those who want to personalize their
shar files.
This option produces vanilla shars which rely only upon the
existence of echo, test and sed in the unpacking
environment.
The -V disables options offensive to the network cop
(or brown shirt). It also changes the default from mixed mode
-M to text mode -T. Warnings are produced if option
-B, -z, -Z, -p or -M is specified
(any of which does or might require uudecode, gzip or
compress in the unpacking environment).
-P
--no-piping
In the shar file, use a temporary file to hold the file to
uudecode, instead of using pipes. This option is mandatory
when you know the unpacking uudecode is unwilling to merely
read its standard input. Richard Marks wrote what is certainly the
most (in)famous of these, for MSDOS :-).
(Here is a side note from the maintainer. Why isnt't this option
the default? In the past history of shar, it was decided
that piping was better, surely because it is less demanding on disk
space, and people seem to be happy with this. Besides, I think
that the uudecode from Richard Marks, on MSDOS, is wrong in
refusing to handle stdin. So far that I remember, he has
the strong opinion that a program without any parameters should
give its --help output. Besides that, should I say, his
uuencode and uudecode programs are full-featured, one
of the most complete set I ever saw. But Richard will not release
his sources, he wants to stay in control.)
-x
--no-check-existing
Overwrite existing files without checking. If neither -x nor
-X is specified, when unpacking itself, the shell archive will
check for and not overwrite existing files (unless -c is passed
as a parameter to the script when unpacking).
-X
--query-user
Interactively overwrite existing files.
Use of -X produces shars which will cause problems
with some unshar-style procedures, particularily when used
together with vanilla mode (-V). Use this feature mainly for
archives to be passed among agreeable parties. Certainly, -X
is not for shell archives which are to be submitted to Usenet
or other public networks.
The problem is that unshar programs or procedures often feed
`/bin/sh' from its standard input, thus putting `/bin/sh'
and the shell archive script in competition for input lines. As an
attempt to alleviate this problem, shar will try to detect if
`/dev/tty' exists at the receiving site and will use it to read
user replies. But this does not work in all cases, it may happen that
the receiving user will have to avoid using unshar programs
or procedures, and call /bin/sh directly. In vanilla mode,
using `/dev/tty' is not even attempted.
-m
--no-timestamp
Avoid generating touch commands to restore the file modification
dates when unpacking files from the archive.
When the timestamp relationship is not preserved, some files like
`configure' or `*.info' may be uselessly remade after
unpacking. This is why, when this option is not used, a special
effort is made to restore timestamps,
-Q
--quiet-unshar
Verbose off at unshar time. Disables the inclusion of
comments to be output when the archive is unpacked.
-f
--basename
Use only the last file name component of each input file name, ignoring
any prefix directories. This is sometimes useful when building a shar
from several directories, or another directory. If a directory name
is passed to shar, the substructure of that directory will be
restored whether -f is specified or not.