This is Info file tar.info, produced by Makeinfo-1.64 from the input file /ade-src/fsf/tar/doc/tar.texinfo. START-INFO-DIR-ENTRY * tar: (tar). Making tape (or disk) archives. END-INFO-DIR-ENTRY This file documents GNU `tar', a utility used to store, backup, and transport files. Copyright (C) 1992, 1994, 1995 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Foundation. File: tar.info, Node: Archive Reading Options, Next: File Writing Options, Prev: Extracting Archive Members, Up: Extracting Archive Members Options to Help Read Archives ----------------------------- *(This message will disappear, once this node revised.)* FIXME: each option wants its own node. summary after menu Normally, `tar' will request data in full block increments from an archive storage device. If the device cannot return a full block, `tar' will report an error. However, some devices do not always return full blocks, or do not require the last block of an archive to be padded out to the next block boundary. To keep reading until you obtain a full block, or to accept an incomplete block if it contains an end-of-archive marker, specify the `--read-full-blocks' (`-B') option in conjunction with the `--extract' (`-x') or `--list' (`-t') operations. FIXME: xref Listing Contents The `--read-full-blocks' (`-B') option is turned on by default when `tar' reads an archive from standard input, or from a remote machine. This is because on BSD Unix systems, attempting to read a pipe returns however much happens to be in the pipe, even if it is less than was requested. If this option were not enabled, `tar' would fail as soon as it read an incomplete block from the pipe. If you're not sure of the blocking factor of an archive, you can read the archive by specifying `--read-full-blocks' (`-B') and `--block-size=512-SIZE' (`-b 512-SIZE'), using a blocking factor larger than what the archive uses. This lets you avoid having to determine the blocking factor of an archive. FIXME: xref Blocking Factor `--read-full-blocks' Use in conjunction with `--extract' (`-x') to read an archive which contains incomplete blocks, or one which has a blocking factor less than the one specified. Normally `tar' stops reading when it encounters a block of zeros between file entries (which usually indicates the end of the archive). `--ignore-zeros' (`-i') allows `tar' to completely read an archive which contains a block of zeros before the end (i.e. a damaged archive, or one which was created by `cat'-ing several archives together). The `--ignore-zeros' (`-i') option is turned off by default because many versions of `tar' write garbage after the end-of-archive entry, since that part of the media is never supposed to be read. GNU `tar' does not write after the end of an archive, but seeks to maintain compatablity among archiving utilities. `--ignore-zeros' To ignore blocks of zeros (ie. end-of-archive entries) which may be encountered while reading an archive. Use in conjunction with `--extract' (`-x') or `--list' (`-t'). If you are using a machine with a small amount of memory, and you need to process large list of file names, you can reduce the amount of space `tar' needs to process the list. To do so, specify the `--same-order' (`-s') option and provide an ordered list of file names. This option tells `tar' that the NAME arguments provided on the command line, or read from a file using the `--files-from=FILE-OF-NAMES' (`-T FILE-OF-NAMES') option, are listed in the same order as the files in the archive. You can create a file containing an ordered list of files in the archive by storing the output produced by `tar --list --file=ARCHIVE-NAME'. FIXME: xref Listing Contents , for information on the `--list' (`-t') operation. This option is probably never needed on modern computer systems. `--same-order' `--preserve-order' To process large lists of file names on machines with small amounts of memory. Use in conjunction with `--compare' (`-d'), `--list' (`-t') or `--extract' (`-x'). FIXME: we don't need/want --preserve to exist any more File: tar.info, Node: File Writing Options, Next: Scarce Disk Space, Prev: Archive Reading Options, Up: Extracting Archive Members Changing How `tar' Writes Files ------------------------------- FIXME: find a better title *(This message will disappear, once this node revised.)* Normally, `tar' writes extracted files into the file system without regard to the files already on the system--files with the same name as archive members are overwritten. To prevent `tar' from extracting an archive member from an archive, if doing so will overwrite a file in the file system, use `--keep-old-files' (`-k') in conjunction with the `--extract' (`-x') operation. When this option is specified, `tar' reports an error stating the name of the files in conflict, instead of writing the file from the archive. `--keep-old files' Prevents `tar' from overwriting files in the file system during extraction. Normally, `tar' sets the modification times of extracted files to the modification times recorded for the files in the archive, but limits the permissions of extracted files by the current `umask' setting. To set the modification times of extracted files to the time when the files were extracted, use the `--modification-time' (`-m') option in conjunction with `--extract' (`-x'). `--modification-time' Sets the modification time of extracted archive members to the time they were extracted, not the time recorded for them in the archive. Use in conjunction with `--extract' (`-x'). To set the modes (access permissions) of extracted files to those recorded for those files in the archive, use the {No Value For "same-persmissions"} option in conjunction with the `--extract' (`-x') operation. FIXME: mib --- should be aliased to ignore-umask. `--preserve-permission' `--same-permission' `--ignore-umask' Set modes of extracted archive members to those recorded in the archive, instead of current umask settings. Use in conjunction with `--extract' (`-x'). FIXME: following paragraph needs to be rewritten: why doesnt' this cat FIXME: files together, why is this useful. is it really useful with FIXME: more than one file? To write the files extracted to the standard output, instead of creating the files on the file system, use `--to-stdout' (`-O') in conjunction with `--extract' (`-x'). This option is useful if you are extracting files to send them through a pipe, and do not need to preserve them in the file system. `--to-stdout' Writes files to the standard output. Used in conjunction with `--extract' (`-x'). FIXME: why would you want to do such a thing, how are files separated on FIXME: the standard output? is this useful with more that one file? are FIXME: pipes the real reason? File: tar.info, Node: Scarce Disk Space, Prev: File Writing Options, Up: Extracting Archive Members Recovering From Scarce Disk Space --------------------------------- *(This message will disappear, once this node revised.)* If a previous attempt to extract files failed due to lack of disk space, you can use `--starting-file=NAME' (`-K NAME') to start extracting only after file NAME when extracting files from the archive. This assumes, of course, that there is now free space, or that you are now extracting into a different file system. `--starting-file=FILE NAME' `-K FILE NAME' Starts an operation in the middle of an archive. Use in conjunction with `--extract' (`-x') or `--list' (`-t'). If you notice you are running out of disk space during an extraction operation, you can also suspend `tar', remove unnecessary files from the file system, and then restart the same `tar' operation. In this case, `--starting-file=NAME' (`-K NAME') is not necessary. FIXME: xref --incremental, xref --interactive, xref --exclude File: tar.info, Node: Comparing Archives Members with Files, Next: Matching Format Parameters, Prev: Extracting Archive Members, Up: Basic tar Operations Comparing Archives Members with Files ===================================== *(This message will disappear, once this node revised.)* The `--compare' (`-d') or `--diff' option compares the contents of the specified archive members against the files with the same names, and reports its findings. If no members are named on the command line, or through `--files-from=FILE-OF-NAMES' (`-T FILE-OF-NAMES'), then the entire archive is so compared. File: tar.info, Node: Matching Format Parameters, Prev: Comparing Archives Members with Files, Up: Basic tar Operations Matching the Format Parameters ============================== *(This message will disappear, once this node revised.)* Some format parameters must be taken into consideration when modifying an archive: Compressed archives cannot be modified. You have to specify the block size of the archive when modifying an archive with a non-default block size. Multi-volume archives can be modified like any other archive. To add files to a multi-volume archive, you need to only mount the last volume of the archive media (and new volumes, if needed). For all other operations, you need to use the entire archive. If a multi-volume archive was labeled using `--label=ARCHIVE-LABEL' (`-V ARCHIVE-LABEL') ( FIXME: pxref Archive Label ) when it was created, `tar' will not automatically label volumes which are added later. To label subsequent volumes, specify `--label=ARCHIVE-LABEL' (`-V ARCHIVE-LABEL') again in conjunction with the `--append' (`-r'), `--update' (`-u') or `--concatenate' (`-A') operation. FIXME: example FIXME: xref somewhere, for more information about format parameters. File: tar.info, Node: Specifying Names to tar, Next: Being Careful, Prev: Basic tar Operations, Up: Top Specifying Names to `tar' ************************* *(This message will disappear, once this node revised.)* * Menu: * Changing the Archive Name:: * Characteristics:: * Selection Options:: File: tar.info, Node: Changing the Archive Name, Next: Characteristics, Prev: Specifying Names to tar, Up: Specifying Names to tar Changing the Archive Name ========================= *(This message will disappear, once this node revised.)* By default, `tar' uses an archive file name compiled in when `tar' was built. Usually this refers to some physical tape drive on the machine. Often, the installer of `tar' didn't set the default to anything meaningful at all. As a result, most uses of `tar' need to tell `tar' where to find (or create) the archive. The `--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME') option selects another file to use as the archive. If the archive file name includes a colon (`:'), then it is assumed to be a file on another machine. If the archive file is `USER@HOST:FILE', then FILE is used on the host HOST. The remote host is accessed using the `rsh' program, with a username of USER. If the username is omitted (along with the `@' sign), then your user name will be used. (This is the normal `rsh' behavior.) It is necessary for the remote machine, in addition to permitting your `rsh' access, to have the `/usr/ucb/rmt' program installed. If you need to use a file whose name includes a colon, then the remote tape drive behavior can be inhibited by using the `--force-local' option. If the file name you give to `--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME') is a single dash (`-'), then `tar' will read the archive from (or write it to) standard input (or standard output). The Name of an Archive An archive can be saved as a file in the file system, sent through a pipe or over a network, or written to an I/O device such as a tape or disk drive. To specify the name of the archive, use the `--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME') option. An archive name can be the name of an ordinary file or the name of an I/O device. `tar' always needs an archive name--if you do not specify an archive name, the archive name comes from the environment variable `TAPE' or, if that variable is not specified, a default archive name, which is usually the name of tape unit zero (ie. /dev/tu00). If you use `-' as an ARCHIVE-NAME, `tar' reads the archive from standard input (when listing or extracting files), or writes it to standard output (when creating an archive). If you use `-' as an ARCHIVE-NAME when modifying an archive, `tar' reads the original archive from its standard input and writes the entire new archive to its standard output. FIXME: does standard input and output redirection work with all FIXME: operations? FIXME: need example for standard input and output (screen and keyboard?) To specify an archive file on a device attached to a remote machine, use the following: --file=HOSTNAME:/DEV/FILE NAME `tar' will complete the remote connection, if possible, and prompt you for a username and password. If you use `--file=@HOSTNAME:/DEV/FILE NAME', `tar' will complete the remote connection, if possible, using your username as the username on the remote machine. FIXME: is this clear? `--file=ARCHIVE-NAME' `-f ARCHIVE-NAME' Names the archive to create or operate on. Use in conjunction with any operation. Selecting Archive Members "File Name arguments" specify which files in the file system `tar' operates on, when creating or adding to an archive, or which archive members `tar' operates on, when reading or deleting from an archive. ( FIXME: pxref Reading and Writing .) To specify file names, you can include them as the last arguments on the command line, as follows: tar OPERATION [OPTION1 OPTION2 ..] [FILE NAME-1 FILE NAME-2 ...] If you specify a directory name as a file name argument, all the files in that directory are operated on by `tar'. If you do not specify files when `tar' is invoked, `tar' operates on all the non-directory files in the working directory (if the operation is `--create' (`-c')), all the archive members in the archive (if a read operation is specified), or does nothing (if any other operation is specified). When specifying the names of files or members to `tar', it by default takes the names of the files from the command line. There are other ways, however, to specify file or member names, or to modify the manner in which `tar' selects the files or members upon which to operate. In general, these methods work both for specifying the names of files and archive members. File: tar.info, Node: Characteristics, Next: Selection Options, Prev: Changing the Archive Name, Up: Specifying Names to tar Selecting Files by Characteristic ================================= To avoid crossing file system boundaries when archiving parts of a directory tree, use `--one-file-system' (`-l'). This option only affects files that are archived because they are in a directory that is being archived; files explicitly named on the command line are archived regardless of where they reside. This option is useful for making full or incremental archival backups of a file system. If this option is used in conjunction with `--verbose' (`-v'), files that are excluded are mentioned by name on the standard error. `--one-file-system' Prevents `tar' from crossing file system boundaries when archiving. Use in conjunction with any write operation. To avoid operating on files whose names match a particular pattern, use the `--exclude=PATTERN' or `--exclude-from=FILE-OF-PATTERNS' (`-X FILE-OF-PATTERNS') options. When you specify the `--exclude=PATTERN' option, `tar' ignores files which match the PATTERN, which can be a single file name or a more complex expression. Thus, if you invoke `tar' with `tar --create --exclude=*.o', no files whose names end in `.o' are included in the archive. FIXME: what other things can you use besides "*"? `--exclude-from=FILE-OF-PATTERNS' (`-X FILE-OF-PATTERNS') acts like `--exclude=PATTERN', but specifies a file FILE containing a list of patterns. `tar' ignores files with names that fit any of these patterns. You can use either option more than once in a single command. `--exclude=PATTERN' Causes `tar' to ignore files that match the PATTERN. `--exclude-from=FILE' Causes `tar' to ignore files that match the patterns listed in FILE. FIXME: --exclude-from used to be "--exclude", --exclude didn't used to FIXME: exist. To operate only on files with modification or status-change times after a particular date, use `--after-date=DATE' (`-N DATE'). You can use this option with `--create' (`-c') or `--append' (`-r') to insure only new files are archived, or with `--extract' (`-x') to insure only recent files are resurrected. FIXME: or --newer DATE `--newer-mtime=DATE' acts like `--after-date=DATE' (`-N DATE') but tests just the modification times of the files, ignoring status-change times. FIXME: need example of --newer-mtime with quoted argument Remember that the entire date argument should be quoted if it contains any spaces. *Please Note:* `--after-date=DATE' (`-N DATE') and `--newer-mtime=DATE' should not be used for incremental backups. Some files (such as those in renamed directories) are not selected up properly by these options. FIXME: xref to incremental backup chapter when node name is decided. `--after-date=DATE' `--newer=DATE' `-N DATE' Acts on files only if their modification or inode-changed times are later than DATE. Use in conjunction with any operation. `--newer-mtime=DATE' Acts like `--after-date=DATE' (`-N DATE'), but only looks at modification times. FIXME: following is the getdate date format --- needs to be re-written, FIXME: made a sub-node: Time/Date Formats Accepted by getdate (omitting obscure constructions) The input consists of one or more of: time zone day date year in any order. Those in turn consist of (`|' and `/' mean `or', `[]' means `optional'): time: H am/pm | H:M [am/pm] | H:M:S [am/pm] zone: timezone-name | timezone-name dst day: day-name | day-name, | N day-name date: M/D | M/D/Y | month-name D | month-name D, Y | D month-name | D month-name Y year: Y am can also be a.m., pm can also be p.m. case and spaces around punctuation are not significant. FIXME: month and day names can be abbreviated. * Menu: * Reading Names from a File:: * Excluding Some Files:: * Operating Only on New Files:: * Crossing Filesystem Boundaries:: File: tar.info, Node: Reading Names from a File, Next: Excluding Some Files, Prev: Characteristics, Up: Characteristics Reading Names from a File ------------------------- *(This message will disappear, once this node revised.)* Instead of giving the names of files or archive members on the command line, you can put the names into a file, and then use the `--files-from=FILE-OF-NAMES' (`-T FILE-OF-NAMES') option to `tar'. Give the name of the file which contains the list as the argument to `--files-from=FILE-OF-NAMES' (`-T FILE-OF-NAMES'). The file names should be separated by newlines in the list. If you give a single dash as a file name for `--files-from=FILE-OF-NAMES' (`-T FILE-OF-NAMES'), that is, you specify `--files-from=-' (`-T -'), then the file names are read from standard input. If you want to specify names that might contain newlines, use the `--null' option. Then, the file names should be separated by NUL characters (ASCII 000) instead of newlines. In addition, the `--null' option turns off the `--directory=DIRECTORY' (`-C DIRECTORY') option ( FIXME: pxref Changing Directory ). Reading a List of File Names from a File *(This message will disappear, once this node revised.)* To read file names from a file on the file system, instead of from the command line, use the `--files-from=FILE-OF-NAMES' (`-T FILE-OF-NAMES') option. If you specify `-' as FILE, the file names are read from standard input. Note that using both `--files-from=-' (`-T -') and `--file=-' (`-f -') in the same command will not work unless the operation is `--create' (`-c'). FIXME: xref Archive Name , for an explanation of the `--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME') option. `--files-from=FILE' `-T FILE' Reads file name arguments from a file on the file system, instead of from the command line. Use in conjunction with any operation. File: tar.info, Node: Excluding Some Files, Next: Operating Only on New Files, Prev: Reading Names from a File, Up: Characteristics Excluding Some Files -------------------- *(This message will disappear, once this node revised.)* The `--exclude=PATTERN' option will prevent any file or member which matches the regular expression PATTERN from being operated on. For example, if you want to create an archive with all the contents of `/tmp' except the file `/tmp/foo', you can use the command `tar --create --file=arch.tar --exclude=foo'. If there are many files you want to exclude, you can use the `--exclude-from=FILE-OF-PATTERNS' (`-X FILE-OF-PATTERNS') option. This works just like the `--files-from=FILE-OF-NAMES' (`-T FILE-OF-NAMES') option: specify the name of a file as EXCLUDE-LIST which contains the list of patterns you want to exclude. FIXME: xref Regular Expressions for more information on the syntax and meaning of regular expressions. File: tar.info, Node: Operating Only on New Files, Next: Crossing Filesystem Boundaries, Prev: Excluding Some Files, Up: Characteristics Operating Only on New Files --------------------------- *(This message will disappear, once this node revised.)* The `--after-date=DATE' (`-N DATE') or `--newer=DATE' limits `tar' to only operating on files which have been modified after the date specified. (For more information on how to specify a date, FIXME: xref Date Formats .) A file is considered to have changed if the contents have been modified, or if the owner, permissions, and so forth, have been changed. If you only want `tar' make the date comparison on the basis of the actual contents of the file's modification, then use the `--newer-mtime=DATE' option. You should never use this option for making incremental dumps. To learn how to use `tar' to make backups, FIXME: ref Making Backups File: tar.info, Node: Crossing Filesystem Boundaries, Prev: Operating Only on New Files, Up: Characteristics Crossing Filesystem Boundaries ------------------------------ *(This message will disappear, once this node revised.)* The `--one-file-system' (`-l') option causes `tar' to modify its normal behavior in archiving the contents of directories. If a file in a directory is not on the same filesystem as the directory itself (because it is a mounted filesystem in its own right), then `tar' will not archive that file, or (if it is a directory itself) anything beneath it. This does not necessarily limit `tar' to only archiving the contents of a single filesystem, because all files named on the command line, or through the `--files-from=FILE-OF-NAMES' (`-T FILE-OF-NAMES') option, will always be archived. File: tar.info, Node: Selection Options, Prev: Characteristics, Up: Specifying Names to tar Local file selection ==================== *(This message will disappear, once this node revised.)* Local file selection `-C DIR' `--directory DIR' Change to directory DIR. This option causes `tar' to change into the directory DIR before continuing. This option can be interspersed with the files `tar' is to work on. For example, tar -c iggy ziggy -C baz melvin will place the files `iggy' and `ziggy' from the current directory on the tape, followed by the file `melvin' from the directory `baz'. This option is especially useful when you have several widely separated files that you want to store in the same directory in the archive. Here, the file `melvin' is recorded in the archive under the precise name `melvin', *not* `baz/melvin'. Thus, the archive will contain three files that all appear to have come from the same directory; if the archive is extracted with plain `tar -x', all three files will be created in the current directory. Contrast this with the command: tar -c iggy ziggy bar/melvin which records the third file in the archive under the name `bar/melvin' so that, if plain `tar -x' is used, the third file will be created in a subdirectory named `bar'. Suppose that, without changing your current directory, you want to call `tar' to dump files from `/users/ctd/dipp' say. Then `--directory=DIRECTORY' (`-C DIRECTORY') is for you. You could do things like: tar cfC archive.tar /users/ctd/dipp . (the `.' means the current directory, once the `--directory=DIRECTORY' (`-C DIRECTORY') obeyed). Some people might want some option to extract everything from an archive in the current directory, ignore directory structure in the archive. This is so rarely proper that I doubt such an option would be really useful. It would only help getting around improper `tar' usage, it might even encourage improper usage. In general, `--directory=DIRECTORY' (`-C DIRECTORY') might be used to produce archives with a cleaner structure in the first place. `-T FILENAME' `--files-from=FILENAME' Get names to extract or create from file FILENAME. Instead of taking the list of files to work on from the command line, the list of files to work on is read from the file FILENAME. If FILENAME is given as `-', the list is read from standard input. Note that using both `-T -' and `-f -' will not work unless you are using the `--create' (`-c') command. This is typically useful when you have generated the list of files to archive with `find'. `--null' This option causes `--files-from=FILE-OF-NAMES' (`-T FILE-OF-NAMES') to read file names terminated by a NUL instead of a newline, so files whose names contain newlines can be archived using `--files-from=FILE-OF-NAMES' (`-T FILE-OF-NAMES'). The `--null' option is just like the one in GNU `xargs' and `cpio', and is useful with the `-print0' predicate of GNU `find'. In `tar', `--null' also causes `--directory=DIRECTORY' (`-C DIRECTORY') options to be treated as file names to archive, in case there are any files out there called `-C'. `--exclude=FILE' Exclude file FILE. `-X FILE' `--exclude-from=FILE' Exclude files listed in FILE. This option causes `tar' to read a list of regular expressions (in shell wildcard syntax), one per line, from FILE; `tar' will ignore files matching those regular expressions. Thus if `tar' is called as `tar -c -X foo .' and the file `foo' contains a single line `*.o', no files whose names end in `.o' will be added to the archive. Multiple `--exclude=PATTERN' options may be given. `--absolute-names' Do not strip leading `/'s from file names. By default, GNU `tar' drops a leading `/' on input or output. This option turns off this behavior; it's equivalent to changing to the root directory before running `tar' (except it also turns off the usual warning message). `--one-file-system' Stay in local filesystem when creating archive. This option causes `tar' to not cross filesystem boundaries when archiving parts of a directory tree. This option only affects files that are archived because they are in a directory that is archived; files named on the command line are archived regardless, and they can be from various file systems. This option is useful for making full or incremental archival backups of a filesystem, as with the Unix `dump' command. Files skipped due to this option are mentioned on standard error. `-K NAME' `--starting-file=NAME' Begin at file NAME in the archive. The `--starting-file=NAME' (`-K NAME') option causes `tar' to begin extracting or listing the archive with the file FILENAME, and to consider only the files starting at that point in the archive. This is useful if a previous attempt to extract files failed when it reached FILENAME due to lack of free space. (Assuming, of course, that there is now free space, or that you are now extracting into a different file system.) `-N DATE' `--newer=DATE' `--after-date=DATE' Only store files newer than DATE. This option causes `tar' to only work on files whose modification or inode-changed times are newer than the DATE given. The main use is for creating an archive; then only new files are written. If extracting, only newer files are extracted. Remember that the entire date argument must be quoted if it contains any spaces. The date is parsed using `getdate'. Changing the Names of Members when Archiving * Menu: * Changing Directory:: * Absolute File Names:: File: tar.info, Node: Changing Directory, Next: Absolute File Names, Prev: Selection Options, Up: Selection Options Changing Directory ------------------ *(This message will disappear, once this node revised.)* The `--directory=DIRECTORY' (`-C DIRECTORY') option causes `tar' to change its current working directory to DIRECTORY. Unlike most options, this one is processed at the point it occurs within the list of files to be processed. Consider the following command: tar --create --file=foo.tar -C /etc passwd hosts -C /lib libc.a This command will place the files `/etc/passwd', `/etc/hosts', and `/lib/libc.a' into the archive. However, the names of the archive members will be exactly what they were on the command line: `passwd', `hosts', and `libc.a'. The `--directory=DIRECTORY' (`-C DIRECTORY') option is frequently used to make the archive independent of the original name of the directory holding the files. Note that `--directory=DIRECTORY' (`-C DIRECTORY') options are interpreted consecutively. If `--directory=DIRECTORY' (`-C DIRECTORY') option specifies a relative file name, it is interpreted relative to the then current directory, which might not be the same as the original current working directory of `tar', due to a previous `--directory=DIRECTORY' (`-C DIRECTORY') option. When using `--files-from=FILE-OF-NAMES' (`-T FILE-OF-NAMES') ( FIXME: pxref Reading Names from a File ), you can put `-C' options in the file list. Unfortunately, you cannot put `--directory' options in the file list. (This interpretation can be disabled by using the `--null' option.) Changing the Working Directory Within a List of File Names *(This message will disappear, once this node revised.)* To change working directory in the middle of a list of file names, either on the command line or in a file specified using `--files-from=FILE-OF-NAMES' (`-T FILE-OF-NAMES'), use `--directory=DIRECTORY' (`-C DIRECTORY'). This will change the working directory to the directory DIRECTORY after that point in the list. For example, tar --create iggy ziggy --directory=baz melvin will place the files `iggy' and `ziggy' from the current directory into the archive, followed by the file `melvin' from the directory `baz'. This option is especially useful when you have several widely separated files that you want to store in the same directory in the archive. Note that the file `melvin' is recorded in the archive under the precise name `melvin', *not* `baz/melvin'. Thus, the archive will contain three files that all appear to have come from the same directory; if the archive is extracted with plain `tar --extract', all three files will be written in the current directory. Contrast this with the command tar -c iggy ziggy bar/melvin which records the third file in the archive under the name `bar/melvin' so that, if the archive is extracted using `tar --extract', the third file will be written in a subdirectory named `bar'. `--directory=`directory'' `-C `directory'' Changes the working directory. FIXME: need to test how extract deals with this, and add an example File: tar.info, Node: Absolute File Names, Prev: Changing Directory, Up: Selection Options Absolute File Names ------------------- *(This message will disappear, once this node revised.)* When `tar' extracts archive members from an archive, it strips any leading slashes (`/') from the member name. This causes absolute member names in the archive to be treated as relative file names. This allows you to have such members extracted wherever you want, instead of being restricted to extracting the member in the exact directory named in the archive. For example, if the archive member has the name `/etc/passwd', `tar' will extract it as if the name were really `etc/passwd'. Other `tar' programs do not do this. As a result, if you create an archive whose member names start with a slash, they will be difficult for other people with an inferior `tar' program to use. Therefore, GNU `tar' also strips leading slashes from member names when putting members into the archive. For example, if you ask `tar' to add the file `/bin/ls' to an archive, it will do so, but the member name will be `bin/ls'. If you use the `--absolute-names' (`-P') option, `tar' will do neither of these transformations. FIXME: is this what this does, or does it just preserve the slash? To archive or extract files relative to the root directory, specify the `--absolute-names' (`-P') option. Normally, `tar' acts on files relative to the working directory--ignoring superior directory names when archiving, and ignoring leading slashes when extracting. When you specify `--absolute-names' (`-P'), `tar' stores file names including all superior directory names, and preserves leading slashes. If you only invoked `tar' from the root directory you would never need the `--absolute-names' (`-P') option, but using this option may be more convenient than switching to root. FIXME: should be an example in the tutorial/wizardry section using this FIXME: to transfer files between systems. FIXME: is write access an issue? `--absolute-names' Preserves full file names (inclusing superior dirctory names) when archiving files. Preserves leading slash when extracting files. File: tar.info, Node: Being Careful, Next: Format Control, Prev: Specifying Names to tar, Up: Top Being Even More Careful *********************** * Menu: * Documentation:: * Checking Progress:: * Interactive Operation:: * Write Verification:: * Comparing:: * Portability:: * Write Protection:: File: tar.info, Node: Documentation, Next: Checking Progress, Prev: Being Careful, Up: Being Careful GNU `tar' documentation ======================= Being careful, the first thing is really checking that you are using GNU `tar', indeed. The `--version' option will generate a message giving confirmation that you are using GNU `tar', with the precise version of GNU `tar' you are using. `tar' identifies itself and prints the version number to the standard output, then immediately exits successfully, without doing anything else, ignoring all other options. For example, `tar --version' might return: GNU tar version 1.11.8 Another thing you might want to do is checking the spelling or meaning of some particular `tar' option, without resorting to this manual, for once you have carefully read it. GNU `tar' has a short help feature, triggerable through the `--help' option. By using this option, `tar' will print a usage message listing all available options on standard output, then exit successfully, without doing anything else and ignoring all other options. Even if this is only a brief summary, it may be several screens long. So, if you are not using some kind of scrollable window, you might prefer to use something like: tar --help | less presuming, here, that you like using `less' for a pager. Other popular pagers are `more' and `pg'. The perceptive reader would have noticed some contradiction in the previous paragraphs. It is written that both `--version' and `--help' print something, and have all other options ignored. In fact, they cannot ignore each other, and one of them has to win. We do not specify which is stronger, here; experiment if you really wonder! The short help output is quite succint, and you might have to get back to the full documentation for precise points. If you are reading this paragraph, you already have the `tar' manual in some form. This manual is available in printed form, as a kind of small book. It may printed out of the GNU `tar' distribution, provided you have TeX already installed somewhere, and a laser printer around. Just configure the distribution, execute the command `make dvi', then print `doc/tar.dvi' the usual way (contact your local guru to know how). If GNU `tar' has been conveniently installed at your place, this manual is also available in interactive, hypertextual form as an Info file. Just call `info tar' or, if you do not have the `info' program handy, use the Info reader provided within GNU Emacs, calling `tar' from the main Info menu. File: tar.info, Node: Checking Progress, Next: Interactive Operation, Prev: Documentation, Up: Being Careful Checking `tar' progress ======================= Typically, `tar' performs most operations without reporting any information to the user except error messages. When using `tar' with many options, particularly ones with complicated or difficult-to-predict behavior, it is possible to make serious mistakes. `tar' provides several options that make observing `tar' easier. These options cause `tar' to print information as it progresses in its job, and you might want to use them just for being more careful about what is going on, or merely for entertaining yourself. If you have encountered a problem when operating on an archive, however, you may need more information than just an error message in order to solve the problem. The following options can be helpful diagnostic tools. Normally, the `--list' (`-t') command to list an archive prints just the file names (one per line) and the other commands are silent. When used with most operations, the `--verbose' (`-v') option causes `tar' to print the name of each file or archive member as it is processed. This and the other options which make `tar' print status information can be useful in monitoring `tar'. With `--create' (`-c') or `--extract' (`-x'), `--verbose' (`-v') used once just prints the names of the files or members as they are processed. Using it twice causes `tar' to print a longer listing (reminiscent of `ls -l') for each member. Since `--list' (`-t') already prints the names of the members, `--verbose' (`-v') used once with `--list' (`-t') causes `tar' to print an `ls -l' type listing of the files in the archive. The following examples both extract members with long list output: tar --extract --file=archive.tar --verbose --verbose tar xvv archive.tar Verbose output appears on the standard output except when an archive is being written to the standard output, as with `tar --create --file=- --verbose' (`tar cfv -', or even `tar cv'--if the installer let standard output be the default archive). In that case `tar' writes verbose output to the standard error stream. The `--totals' option--which is only meaningful when used with `--create' (`-c')--causes `tar' to print the total amount written to the archive, after it has been fully created. The `--checkpoint' option prints an occasional message as `tar' reads or writes the archive. In fact, it print directory names while reading the archive. It is designed for those who don't need the more detailed (and voluminous) output of `--record-number' (`-R'), but do want visual confirmation that `tar' is actually making forward progress. FIXME: There is some confusion here. It seems that -R once wrote a FIXME: message at `every' block read or written. The `--show-omitted-dirs' option, when reading an archive--with `--list' (`-t') or `--extract' (`-x'), for example--causes a message to be printed for each directory in the archive which is skipped. This happens regardless of the reason for skipping: the directory might not have been named on the command line (implicitly or explicitly), it might be excluded by the use of the `--exclude=PATTERN' option, or some other reason. If `--record-number' (`-R') is used, `tar' prints, along with every message it would normally produce, the record number within the archive where the message was triggered. This option is especially useful when reading damaged archives, since it helps pinpoint the damaged sections. It can also be used with `--list' (`-t') when listing a file-system backup tape, allowing you to choose among several backup tapes when retrieving a file later, in favor of the tape where the file appears earliest (closest to the front of the tape). FIXME: xref when the node name is set and the backup section written File: tar.info, Node: Interactive Operation, Next: Write Verification, Prev: Checking Progress, Up: Being Careful Asking for Confirmation During Operations ========================================= Typically, `tar' carries out a command without stopping for further instructions. In some situations however, you may want to exclude some files and archive members from the operation (for instance if disk or storage space is tight). You can do this by excluding certain files automatically ( FIXME: pxref File Exclusion ), or by performing an operation interactively, using the `--interactive' (`-w') option. `tar' also accepts `--confirmation' for this option. When the `--interactive' (`-w') option is specified, before reading, writing, or deleting files, `tar' first prints a message for each such file, telling what operation it intends to take, then asks for confirmation on the terminal. The actions which require confirmation include adding a file to the archive, extracting a file from the archive, deleting a file from the archive, and deleting a file from disk. To confirm the action, you must type a line of input beginning with `y'. If your input line begins with anything other than `y', `tar' skips that file. If `tar' is reading the archive from the standard input, `tar' opens the file `/dev/tty' to support the interactive communications. File: tar.info, Node: Write Verification, Next: Comparing, Prev: Interactive Operation, Up: Being Careful Verifying Data as It is Stored ============================== You can insure the accuracy of an archive by comparing files in the system with archive members. `tar' can compare an archive to the file system as the archive is being written, to verify a write operation, or can compare a previously written archive, to insure that it is up to date. To check for discrepancies in an archive immediately after it is written, use the `--verify' (`-W') option in conjunction with the `--create' (`-c') operation. When this option is specified, `tar' checks archive members against their counterparts in the file system, and reports discrepancies on the standard error. In multi-volume archives, each volume is verified after it is written, before the next volume is written. To verify an archive, you must be able to read it from before the end of the last written entry. This option is useful for detecting data errors on some tapes. Archives written to pipes, some cartridge tape drives, and some other devices cannot be verified. File: tar.info, Node: Comparing, Next: Portability, Prev: Write Verification, Up: Being Careful Comparing an Archive with the File System ========================================= *(This message will disappear, once this node revised.)* `--compare' (`-d') compares archive members in an existing archive with their counterparts in the file system, and reports differences in file size, mode, owner, modification date and contents. If a file is represented in the archive but does not exist in the file system, `tar' reports a difference. If you use FILE NAME arguments in conjunction with `tar --compare', `tar' compares the archived versions of the files specified with their counterparts in the file system. If you specify a file that is not in the archive, `tar' will report an error. If you don't specify any files, `tar' compares all the files in the archive. Because `tar' only checks files in the archive against files in the file system, and not vice versa, it ignores files in the file system that do not exist in the archive. The following example compares the archive members `larry', `moe' and `curly' in the archive `stooges' with files of the same name in the file system. tar --compare --file=stooges larry moe curly If a file, for example `curly', did not exist in the archive, `tar' would report an error, as follows: curly: does not exist File: tar.info, Node: Portability, Next: Write Protection, Prev: Comparing, Up: Being Careful Making `tar' Archives More Portable =================================== Creating a `tar' archive on a particular system, meant to be later useful on many other machines and with other versions of `tar', is more a challenge than you might think. `tar' archive formats evolved since the first versions of Unix, many such formats are flying around, not always comptabile between them. This section wants to discuss a few problems, and give some advice, for making `tar' archives more portable. One golden rule is simplicity. For example, limit your `tar' archives to contain only regular files and directories, avoiding other kind of special files. Do not attempt to save sparse files or contiguous files as such. Let's discuss a few more problems, in turn. * Menu: * Portable Names:: * Symbolic Links:: * Old V7 and POSIX:: * Checksumming Problems:: File: tar.info, Node: Portable Names, Next: Symbolic Links, Prev: Portability, Up: Portability Portable Names -------------- Use *straight* file and directory names, made up of printable ASCII characters, avoiding colons, slashes, backslashes, and other *dangerous* characters. Avoid deep directory nesting. Accounting for oldish System V machines, limit your file and directory names to 14 characters or less. If you intend to have your `tar' archives to be read under MSDOS, you should not rely on case distinction for file names, and you might use the GNU `doschk' program for helping you further diagnosing illegal MSDOS names, which are even more limited than System V's. File: tar.info, Node: Symbolic Links, Next: Old V7 and POSIX, Prev: Portable Names, Up: Portability Symbolic Links -------------- Normally, when `tar' archives a symbolic link, it writes a record to the archive naming the target of the link. In that way, the `tar' archive is a faithful record of the filesystem contents. `--dereference' (`-h') is used with `--create' (`-c'), and causes `tar' to archive the files symbolic links point to, instead of the links themselves. When this option is used, when `tar' encounters a symbolic link, it will archive the linked-to file, instead of simply recording the presence of a symbolic link. The name under which the file is stored in the file system is not recorded in the archive. To record both the symbolic link name and the file name in the system, archive the file under both names. If all links were recorded automatically by `tar', an extracted file might be linked to a file name that no longer exists in the file system. If a linked-to file is encountered again by `tar' while creating the same archive, an entire second copy of it will be stored. (This *might* be considered a bug.) So, for portable archives, do not archive symbolic links as such, and use `--dereference' (`-h'): many systems do not support symbolic links, and moreover, your distribution might be unusable if it contains unresolved symbolic links. File: tar.info, Node: Old V7 and POSIX, Next: Checksumming Problems, Prev: Symbolic Links, Up: Portability Old V7 and POSIX Archives ------------------------- GNU `tar' implements an early draft of the POSIX 1003.1 `ustar' standard which is different from the final standard. Adding support for the new changes in a backward-compatible fashion is not trivial. Certain old versions of `tar' cannot handle additional information recorded by newer `tar' programs. To create an archive in V7 format (not ANSI), which can be read by these old versions, specify the `--old-archive' (`-o') option in conjunction with the `--create' (`-c'). `tar' also accepts `--portability' for this option. When you specify it, `tar' leaves out information about directories, pipes, fifos, contiguous files, and device files, and specifies file ownership by group and user IDs instead of group and user names. When updating an archive, do not use `--old-archive' (`-o') unless the archive was created with using this option. In most cases, a *new* format archive can be read by an *old* `tar' program without serious trouble, so this option should seldom be needed. On the other hand, most modern `tar's are able to read old format archives, so it might be safer for you to always use `--old-archive' (`-o') for your distributions.