summaryrefslogtreecommitdiffstats
path: root/doc/tarlz.texi
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2019-04-13 08:59:10 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2019-04-13 08:59:10 +0000
commit29867477a1c50b8cbea6212b8dd649a052778bf0 (patch)
tree070208b9f3add6d1757dc9281b7c8d113eb2768d /doc/tarlz.texi
parentAdding upstream version 0.14. (diff)
downloadtarlz-29867477a1c50b8cbea6212b8dd649a052778bf0.tar.xz
tarlz-29867477a1c50b8cbea6212b8dd649a052778bf0.zip
Adding upstream version 0.15.upstream/0.15
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'doc/tarlz.texi')
-rw-r--r--doc/tarlz.texi55
1 files changed, 38 insertions, 17 deletions
diff --git a/doc/tarlz.texi b/doc/tarlz.texi
index da7abfa..3d2f668 100644
--- a/doc/tarlz.texi
+++ b/doc/tarlz.texi
@@ -6,8 +6,8 @@
@finalout
@c %**end of header
-@set UPDATED 12 March 2019
-@set VERSION 0.14
+@set UPDATED 11 April 2019
+@set VERSION 0.15
@dircategory Data Compression
@direntry
@@ -84,7 +84,8 @@ parallel, multiplying the decompression speed.
@item
New members can be appended to the archive (by removing the EOF
-member) just like to an uncompressed tar archive.
+member), and unwanted members can be deleted from the archive. Just
+like an uncompressed tar archive.
@item
It is a safe posix-style backup format. In case of corruption,
@@ -121,6 +122,9 @@ tarlz [@var{options}] [@var{files}]
@end example
@noindent
+All operations except @samp{--concatenate} operate on whole trees if any
+@var{file} is a directory.
+
On archive creation or appending tarlz archives the files specified, but
removes from member names any leading and trailing slashes and any filename
prefixes containing a @samp{..} component. On extraction, leading and
@@ -206,6 +210,15 @@ run from the root directory to perform the comparison.
Make @samp{--diff} ignore differences in owner and group IDs. This option is
useful when comparing an @samp{--anonymous} archive.
+@item --delete
+Delete the specified files and directories from an archive in place. It
+currently can delete only from uncompressed archives and from archives with
+individually compressed files (@samp{--no-solid} archives). To delete a
+directory without deleting the files under it, use
+@w{@code{tarlz --delete -f foo --exclude='dir/*' dir}}. Deleting in place
+may be dangerous. A corrupt archive, a power cut, or an I/O error may cause
+data loss.
+
@item --exclude=@var{pattern}
Exclude files matching a shell pattern like @samp{*.o}. A file is considered
to match if any component of the filename matches. For example, @samp{*.o}
@@ -266,8 +279,10 @@ Verbosely list files processed.
@item -x
@itemx --extract
-Extract files from an archive. If @var{files} are given, extract only
-the @var{files} given. Else extract all the files in the archive.
+Extract files from an archive. If @var{files} are given, extract only the
+@var{files} given. Else extract all the files in the archive. To extract a
+directory without extracting the files under it, use
+@w{@code{tarlz -xf foo --exclude='dir/*' dir}}.
@item -0 .. -9
Set the compression level for @samp{--create} and @samp{--append}. The
@@ -474,7 +489,9 @@ If several extended headers precede an ustar header, only the last
extended header takes effect. The other extended headers are ignored.
Similarly, if several records with the same keyword appear in the same
block of extended records, only the last record for the repeated keyword
-takes effect. The other records for the repeated keyword are ignored.
+takes effect. The other records for the repeated keyword are ignored.@*
+A global header inserted between an extended header and an ustar header.@*
+An extended header just before the EOF blocks.
@end ignore
@sp 1
@@ -654,7 +671,7 @@ and gname are null-terminated character strings except when all characters
in the array contain non-null characters including the last character. Each
numeric field contains a leading space- or zero-filled, optionally
null-terminated octal number using digits from the ISO/IEC 646:1991 (ASCII)
-standard. Tarlz is able to decode numeric fields 1 byte larger than standard
+standard. Tarlz is able to decode numeric fields 1 byte longer than standard
ustar by not requiring a terminating null character.
@@ -663,10 +680,10 @@ ustar by not requiring a terminating null character.
@cindex Amendments to pax format
Tarlz is meant to reliably detect invalid or corrupt metadata during
-extraction and to not create safety risks in the archives it creates. In
-order to achieve these goals, tarlz makes some changes to the variant of the
-pax format that it uses. This chapter describes these changes and the
-concrete reasons to implement them.
+decoding, and to create safe archives where corrupt metadata can be reliably
+detected. In order to achieve these goals, tarlz makes some changes to the
+variant of the pax format that it uses. This chapter describes these changes
+and the concrete reasons to implement them.
@sp 1
@anchor{crc32}
@@ -713,9 +730,9 @@ extended records.
If an extended header is required for any reason (for example a file size
larger than @w{8 GiB} or a link name longer than 100 bytes), tarlz moves the
filename also to the extended header to prevent an ustar tool from trying to
-extract the file or link. This also makes easier during parallel extraction
-or listing the detection of a tar member split between two lzip members at
-the boundary between the extended header and the ustar header.
+extract the file or link. This also makes easier during parallel decoding
+the detection of a tar member split between two lzip members at the boundary
+between the extended header and the ustar header.
@sp 1
@section As simple as possible (but not simpler)
@@ -726,6 +743,10 @@ exceed the limits of the ustar format. Adding extended headers to each
member just to record subsecond timestamps seems wasteful for a backup
format.
+Global pax headers are tolerated, but not supported; they are parsed and
+ignored. Some operations may not behave as expected if the archive contains
+global headers.
+
@sp 1
@section Avoid misconversions to/from UTF-8
@@ -886,11 +907,11 @@ tarlz -xf archive.tar.lz
@sp 1
@noindent
-Example 7: Extract files @samp{a} and @samp{c} from archive
-@samp{archive.tar.lz}.
+Example 7: Extract files @samp{a} and @samp{c}, and the whole tree under
+directory @samp{dir1} from archive @samp{archive.tar.lz}.
@example
-tarlz -xf archive.tar.lz a c
+tarlz -xf archive.tar.lz a c dir1
@end example
@sp 1