diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/tarlz.1 | 9 | ||||
| -rw-r--r-- | doc/tarlz.info | 78 | ||||
| -rw-r--r-- | doc/tarlz.texi | 55 |
3 files changed, 93 insertions, 49 deletions
diff --git a/doc/tarlz.1 b/doc/tarlz.1 index a17e58d..4308fc2 100644 --- a/doc/tarlz.1 +++ b/doc/tarlz.1 @@ -1,5 +1,5 @@ .\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.46.1. -.TH TARLZ "1" "March 2019" "tarlz 0.14" "User Commands" +.TH TARLZ "1" "April 2019" "tarlz 0.15" "User Commands" .SH NAME tarlz \- creates tar archives with multimember lzip compression .SH SYNOPSIS @@ -31,7 +31,7 @@ display this help and exit output version information and exit .TP \fB\-A\fR, \fB\-\-concatenate\fR -append tar.lz archives to the end of an archive +append archives to the end of an archive .TP \fB\-B\fR, \fB\-\-data\-size=\fR<bytes> set target size of input data blocks [2x8=16 MiB] @@ -48,6 +48,9 @@ find differences between archive and file system \fB\-\-ignore\-ids\fR ignore differences in owner and group IDs .TP +\fB\-\-delete\fR +delete files/directories from an archive +.TP \fB\-\-exclude=\fR<pattern> exclude files matching a shell pattern .TP @@ -73,7 +76,7 @@ list the contents of an archive verbosely list files processed .TP \fB\-x\fR, \fB\-\-extract\fR -extract files from an archive +extract files/directories from an archive .TP \fB\-0\fR .. \fB\-9\fR set compression level [default 6] diff --git a/doc/tarlz.info b/doc/tarlz.info index fc1f092..f49bb43 100644 --- a/doc/tarlz.info +++ b/doc/tarlz.info @@ -11,7 +11,7 @@ File: tarlz.info, Node: Top, Next: Introduction, Up: (dir) Tarlz Manual ************ -This manual is for Tarlz (version 0.14, 12 March 2019). +This manual is for Tarlz (version 0.15, 11 April 2019). * Menu: @@ -59,7 +59,8 @@ archive, but it has the following advantages: parallel, multiplying the decompression speed. * 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. * It is a safe posix-style backup format. In case of corruption, tarlz can extract all the undamaged members from the tar.lz @@ -88,8 +89,11 @@ The format for running tarlz is: tarlz [OPTIONS] [FILES] -On archive creation or appending tarlz archives the files specified, but -removes from member names any leading and trailing slashes and any +All operations except '--concatenate' operate on whole trees if any +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 '..' component. On extraction, leading and trailing slashes are also removed from member names, and archive members containing a '..' component in the filename are skipped. Tarlz @@ -176,6 +180,15 @@ equivalent to '-1 --solid' Make '--diff' ignore differences in owner and group IDs. This option is useful when comparing an '--anonymous' archive. +'--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 ('--no-solid' + archives). To delete a directory without deleting the files under + it, use '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. + '--exclude=PATTERN' Exclude files matching a shell pattern like '*.o'. A file is considered to match if any component of the filename matches. For @@ -240,8 +253,10 @@ equivalent to '-1 --solid' '-x' '--extract' - Extract files from an archive. If FILES are given, extract only - the FILES given. Else extract all the files in the archive. + Extract files from an archive. If FILES are given, extract only the + FILES given. Else extract all the files in the archive. To extract + a directory without extracting the files under it, use + 'tarlz -xf foo --exclude='dir/*' dir'. '-0 .. -9' Set the compression level for '--create' and '--append'. The @@ -597,7 +612,7 @@ 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 ustar by not requiring a terminating null +byte longer than standard ustar by not requiring a terminating null character. @@ -607,10 +622,10 @@ File: tarlz.info, Node: Amendments to pax format, Next: Multi-threaded tar, P ****************************************** 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. 4.1 Add a CRC of the extended records @@ -659,9 +674,9 @@ overridden by extended records. size larger than 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. +parallel decoding the detection of a tar member split between two lzip +members at the boundary between the extended header and the ustar +header. 4.3 As simple as possible (but not simpler) @@ -673,6 +688,10 @@ of a file 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. + 4.4 Avoid misconversions to/from UTF-8 ====================================== @@ -817,9 +836,10 @@ Example 6: Extract all files from archive 'archive.tar.lz'. tarlz -xf archive.tar.lz -Example 7: Extract files 'a' and 'c' from archive 'archive.tar.lz'. +Example 7: Extract files 'a' and 'c', and the whole tree under +directory 'dir1' from archive 'archive.tar.lz'. - tarlz -xf archive.tar.lz a c + tarlz -xf archive.tar.lz a c dir1 Example 8: Copy the contents of directory 'sourcedir' to the directory @@ -869,19 +889,19 @@ Concept index Tag Table: Node: Top223 Node: Introduction1086 -Node: Invoking tarlz3280 -Ref: --data-size5339 -Ref: --bsolid11442 -Node: File format15072 -Ref: key_crc3219892 -Node: Amendments to pax format25309 -Ref: crc3225833 -Ref: flawed-compat26858 -Node: Multi-threaded tar29225 -Node: Minimum archive sizes31764 -Node: Examples33897 -Node: Problems35566 -Node: Concept index36092 +Node: Invoking tarlz3337 +Ref: --data-size5489 +Ref: --bsolid12172 +Node: File format15802 +Ref: key_crc3220622 +Node: Amendments to pax format26039 +Ref: crc3226580 +Ref: flawed-compat27605 +Node: Multi-threaded tar30128 +Node: Minimum archive sizes32667 +Node: Examples34800 +Node: Problems36517 +Node: Concept index37043 End Tag Table 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 |