From 9855bc011ecbcf2d7b93ef6b2d0ea3af70fcd585 Mon Sep 17 00:00:00 2001 From: Sergey Poznyakoff Date: Thu, 16 Nov 2017 18:12:36 +0200 Subject: Update docs * doc/Makefile.am: Add recipes.texi * doc/recipes.texi: New file. * doc/tar.texi: New appendix "Recipes" --- doc/Makefile.am | 1 + doc/recipes.texi | 134 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/tar.texi | 72 ++++-------------------------- 3 files changed, 143 insertions(+), 64 deletions(-) create mode 100644 doc/recipes.texi (limited to 'doc') diff --git a/doc/Makefile.am b/doc/Makefile.am index 98ff3ffa..cb69b743 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -28,6 +28,7 @@ tar_TEXINFOS = \ header.texi\ intern.texi\ parse-datetime.texi\ + recipes.texi\ rendition.texi\ snapshot.texi\ sparse.texi\ diff --git a/doc/recipes.texi b/doc/recipes.texi new file mode 100644 index 00000000..da259da3 --- /dev/null +++ b/doc/recipes.texi @@ -0,0 +1,134 @@ +@c This is part of the GNU tar manual. +@c Copyright (C) 2017 Free Software Foundation, Inc. +@c This file is distributed under GFDL 1.3 or any later version +@c published by the Free Software Foundation. + +This appendix provides several recipes for performing common tasks +using @GNUTAR{}. + +@menu +* copy directory hierarchy:: +* intermediate directories:: +@end menu + +@node copy directory hierarchy +@appendixsec Copying directory hierarchies + +This is a traditional way to copy a directory hierarchy preserving +the dates, modes, owners and link-structure of all the files therein. +It was used back when the @command{cp} command lacked the @option{-a} +option: + +@smallexample +$ @kbd{(cd sourcedir; tar -cf - .) | (cd targetdir; tar -xf -)} +@end smallexample + +@noindent +You can avoid subshells by using @option{-C} option: + +@smallexample +$ @kbd{tar -C sourcedir -cf - . | tar -C targetdir -xf -} +@end smallexample + +@noindent +The same command using long option forms: + +@smallexample +@group +$ @kbd{(cd sourcedir; tar --create --file=- . ) \ + | (cd targetdir; tar --extract --file=-)} +@end group +@end smallexample + +@noindent +or + +@smallexample +@group +$ @kbd{tar --directory sourcedir --create --file=- . \ + | tar --directory targetdir --extract --file=-} +@end group +@end smallexample + +@node intermediate directories +@appendixsec Restoring Intermediate Directories + +A common concern is how to extract permissions and ownerships of +intermediate directories when extracting only selected members from +the archive. To illustrate this, consider the following archive: + +@example +@group +# tar tvf A.tar +drwxr-xr-x root/root 0 2017-11-16 14:39 foo/ +dr-xr-x--- gray/user 0 2017-11-16 14:39 foo/bar/ +-rw-r--r-- gray/user 10 2017-11-16 14:40 foo/bar/file +@end group +@end example + +Suppose you extract only the file @file{foo/bar/file}, while being +@samp{root}: + +@example +# @kbd{tar xvf A.tar foo/bar/file} +foo/bar/file +@end example + +Now, let's inspect the content of the created directories: + +@example +@group +# find foo -ls +427257 0 drwxr-xr-x 3 root root 16 Nov 17 16:10 foo +427258 0 drwxr-xr-x 2 root root 17 Nov 17 16:10 foo/bar +427259 0 -rw-r--r-- 1 gray user 10 Nov 6 14:40 foo/bar/file +@end group +@end example + +The requested file is restored, including its ownership and +permissions. The intermediate directories, however, are created with +the default permissions, current timestamp and owned by the current +user. This is because by the time @command{tar} has reached the requested file, +it had already skipped the entries for its parent directories, so it +has no iformation about their ownership and modes. + +To restore meta information about the intermediate directories, +you'll need to specify them explicitly in the command line and use the +@option{--no-recursive} option (@pxref{recurse}) to avoid extracting +their content. + +To automate this process, @cite{Neal P. Murphy} proposed the following +shell script@footnote{The original version of the script can be +seen at @uref{http://lists.gnu.org/archive/html/bug-tar/2016-11/msg00024.html}}: + +@example +@group +#! /bin/sh +(while read path + do + path=`dirname $path` + while [ -n "$path" -a "$path" != "." ] + do + echo $path + path=`dirname $path` + done + done < $2 | sort | uniq) | + tar -x --no-recursion -v -f $1 -T - -T $2 +@end group +@end example + +The script takes two arguments: the name of the archive file, and the +name of the file list file. + +To complete our example, the file list will contain single line: + +@example +foo/bar/file +@end example + +Supposing its name is @file{file.list} and the script is named +@file{restore.sh}, you can invoke it as follows: + +@example +# @kbd{sh restore.sh A.tar file.list} +@end example diff --git a/doc/tar.texi b/doc/tar.texi index 5d2d057a..ec657f53 100644 --- a/doc/tar.texi +++ b/doc/tar.texi @@ -36,7 +36,7 @@ This manual is for @acronym{GNU} @command{tar} (version @value{VERSION}, @value{UPDATED}), which creates and extracts files from archives. -Copyright @copyright{} 1992, 1994--1997, 1999--2001, 2003--2016 Free +Copyright @copyright{} 1992, 1994--1997, 1999--2001, 2003--2017 Free Software Foundation, Inc. @quotation @@ -111,6 +111,7 @@ document. The rest of the menu lists all the lower level nodes. Appendices * Changes:: +* Recipes:: Frequently used tar recipes * Configuring Help Summary:: * Fixing Snapshot Files:: * Tar Internals:: @@ -204,7 +205,6 @@ All @command{tar} Options * create options:: * extract options:: * backup:: -* Applications:: * looking ahead:: Advanced @GNUTAR{} Operations @@ -4777,7 +4777,6 @@ expanded by the shell when invoking @command{tar}. * create options:: * extract options:: * backup:: -* Applications:: * looking ahead:: @end menu @@ -6501,65 +6500,6 @@ set, the default is @samp{~}, just as in Emacs. @end table -@node Applications -@section Notable @command{tar} Usages -@UNREVISED - -@FIXME{Using Unix file linking capability to recreate directory -structures---linking files into one subdirectory and then -@command{tar}ring that directory.} - -@FIXME{Nice hairy example using absolute-names, newer, etc.} - -@findex uuencode -You can easily use archive files to transport a group of files from -one system to another: put all relevant files into an archive on one -computer system, transfer the archive to another system, and extract -the contents there. The basic transfer medium might be magnetic tape, -Internet FTP, or even electronic mail (though you must encode the -archive with @command{uuencode} in order to transport it properly by -mail). Both machines do not have to use the same operating system, as -long as they both support the @command{tar} program. - -For example, here is how you might copy a directory's contents from -one disk to another, while preserving the dates, modes, owners and -link-structure of all the files therein. In this case, the transfer -medium is a @dfn{pipe}: - -@smallexample -$ @kbd{(cd sourcedir; tar -cf - .) | (cd targetdir; tar -xf -)} -@end smallexample - -@noindent -You can avoid subshells by using @option{-C} option: - -@smallexample -$ @kbd{tar -C sourcedir -cf - . | tar -C targetdir -xf -} -@end smallexample - -@noindent -The command also works using long option forms: - -@smallexample -@group -$ @kbd{(cd sourcedir; tar --create --file=- . ) \ - | (cd targetdir; tar --extract --file=-)} -@end group -@end smallexample - -@noindent -or - -@smallexample -@group -$ @kbd{tar --directory sourcedir --create --file=- . \ - | tar --directory targetdir --extract --file=-} -@end group -@end smallexample - -@noindent -This is one of the easiest methods to transfer a @command{tar} archive. - @node looking ahead @section Looking Ahead: The Rest of this Manual @@ -12932,8 +12872,8 @@ understand their security implications. @appendix Changes This appendix lists some important user-visible changes between -version @GNUTAR{} @value{VERSION} and previous versions. An up-to-date -version of this document is available at +various versions of @GNUTAR{}. An up-to-date version of this document +is available at @uref{http://www.gnu.org/@/software/@/tar/manual/changes.html,the @GNUTAR{} documentation page}. @@ -13019,6 +12959,10 @@ These options are deprecated. Please use @option{--format=v7} instead. This option is deprecated. Please use @option{--format=posix} instead. @end table +@node Recipes +@appendix Recipes +@include recipes.texi + @node Configuring Help Summary @appendix Configuring Help Summary -- cgit v1.2.1