Geek Gadgets 1

home *** CD-ROM | disk | FTP | other *** search

/ Geek Gadgets 1 / ADE-1.bin / ade-dist / tar-1.11.8-bin.lha / info / tar.info-3 (.txt) < prev next >

Wrap

GNU Info File | 1996-10-12 | 50KB | 1,113 lines

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: Old Options, Next: Mixing Styles, Prev: Short Options, Up: Option Styles Old Option Style ---------------- *(This message will disappear, once this node revised.)* Old options are single letters not preceeded by any dash at all, and appearing *only* in the position immediately following the `tar' keyword in the command, after some white space. The letter of an old option is exactly the same letter as the corresponding short option. For example, the old option `t' is the same as the short option `-t', and consequently, the same as long option `--list' (`-t'). As far as we know, all `tar' programs, GNU and non-GNU, support old options. GNU `tar' supports them not only for historical reasons, but also because many people are used to them. All old options should be written as a single argument, without separating spaces, by lumping together all letters specifying these options. This set of letters should be the first to appear on the command line, after the `tar' program name; old options cannot appear anywhere else. Then, for any old option required an argument, the argument should follow on the command line. Arguments to the options should appear in the same order as the letters to which they correspond. The `tar' command synopsis might be rewritten: tar LETTER... [ARGUMENT]... [OPTION]... [NAME]... when old options are being used. This command syntax is useful because it lets you type the single letter forms of the operation and options as a single argument to `tar', without writing preceding `-'s or inserting spaces between letters. `tar cv' or `tar -cv' are equivalent to `tar -c -v'. For compatibility with Unix `tar', the first argument can contain an option letter (or a cluster of option letters) *not* introduced by a dash; for example, `tar cv' specifies the option `-v' in addition to the command `-c'. When options that need arguments are given together with the command, all the associated arguments follow, in the same order as the options. Thus, the example above could also be written in the old style as follows: tar cvbf 20 /dev/rmt0 Here `20' is the argument of `-b' and `/dev/rmt0' is the argument of `-f'. On the other hand, this old style syntax makes it difficult to match option letters with their corresponding arguments, and is often confusing. In the command `tar cvbf 20 /dev/rmt0', for example, `20' is the argument for `-b', `/dev/rmt0' is the argument for `-f', and `-v' does not have a corresponding argument. Even using short options like in `tar -c -v -b 20 -f /dev/rmt0' is clearer, putting all arguments next to the option they pertain to. If you want to reorder the letters in the old option argument, be sure to appropriately reorder any corresponding argument. This old way of writing `tar' options can surprise even experienced users. For example, the two commands: tar cfz archive.tar.gz file tar -cfz archive.tar.gz file are quite different. The first example uses `archive.tar.gz' as the value for option `f' and recognizes the option `z'. The second example, however, uses `z' as the value for option `f'--probably not what was intended. (I find it quite inelegant that `getopt' batches the remaining `z' as the value for `f'. I think that clarity dictates that clustering of option letters, when some require arguments, should be diagnosed and disallowed. But compatibility with traditional systems dictates it.) This second example could be corrected in many ways, among which: tar -czf archive.tar.gz file tar -cf archive.tar.gz -z file tar cf archive.tar.gz -z file File: tar.info, Node: Mixing Styles, Prev: Old Options, Up: Option Styles Mixing Option Styles -------------------- All three styles may be intermixed in a single `tar' command, as long as the rules for each style are fully respected. In GNU `tar' up to 1.11.6, using old style options was cutting out the possibility of using many options not having short forms. Many users rightly expressed their frustration at fighting with the current `tar' option decoder, so I changed it. However, GNU `tar' needs to be compatible with other `tar's, in the things that other `tar's can do. Short options should provide upward compatibility. So, if the current option decoding raises incompatibilities, please let me know. Old style options and modern options may be mixed on a single call to the `tar' program. However, old style options should be introduced in the first argument only; modern options may be given only after all arguments to old style options have been collected. If this rule is not respected, a modern option might be falsely interpreted as the value of the argument to one of the old style options. For example, currently, all the following commands are wholly equivalent, and illustrate many combinations and orderings of option styles. tar --create --file=archive.tar tar --create -f archive.tar tar --create -farchive.tar tar --file=archive.tar --create tar --file=archive.tar -c tar -c --file=archive.tar tar -c -f archive.tar tar -c -farchive.tar tar -cf archive.tar tar -cfarchive.tar tar -f archive.tar --create tar -f archive.tar -c tar -farchive.tar --create tar -farchive.tar -c tar c --file=archive.tar tar c -f archive.tar tar c -farchive.tar tar cf archive.tar tar f archive.tar --create tar f archive.tar -c tar fc archive.tar On the other hand, the following commands are *not* equivalent to the previous set: tar -f -c archive.tar tar -fc archive.tar tar -fcarchive.tar tar -farchive.tarc tar cfarchive.tar These last examples mean something completely different of what the user might have intended. The first four specify that the `tar' archive would be a file named `-c', `c', `carchive.tar' or `archive.tarc', respectively. The first two examples also specify a single non-option, NAME argument having value `archive.tar'. The last example contains only old style option letters (repeating option `c' twice) and no argument value. File: tar.info, Node: Options, Prev: Option Styles, Up: Invoking tar All Available Options ===================== *(This message will disappear, once this node revised.)* Options change the way `tar' performs an operation. `--absolute-names' `--after-date=DATE' Limit the operation to files changed after the given date. FIXME: xref File Exclusion . `--block-size=NUMBER' Specify the blocking factor of an archive. FIXME: xref Blocking Factor . `--compress' Specify a compressed archive. FIXME: xref Compressed Archives . `--compress-block.' Create a whole block sized compressed archive. FIXME: xref Compressed Archives . `--confirmation' Solicit confirmation for each file. FIXME: xref Interactive Operation FIXME: --selective should be a synonym. `--dereference' Treat a symbolic link as an alternate name for the file the link points to. FIXME: xref Symbolic Links . `--directory=`directory'' Change the working directory. FIXME: xref Changing Working Directory . `--exclude=PATTERN' Exclude files which match the regular expression PATTERN. FIXME: xref File Exclusion . `--exclude-from=`file'' Exclude files which match any of the regular expressions listed in the file `file'. FIXME: xref File Exclusion . `--file=ARCHIVE-NAME' Name the archive. FIXME: xref Archive Name ). `--files-from=`file'' Read file name arguments from a file on the file system. FIXME: xref File Name Lists . `--ignore-umask' Set modes of extracted files to those recorded in the archive. FIXME: xref File Writing Options . `--ignore-zeros' Ignore end-of-archive entries. FIXME: xref Archive Reading Options . FIXME: this should be changed to --ignore-end `--tape-length=N (-L)' FIXME: alternate way of doing multi archive, will go to that length and FIXME: prompts for new tape, automatically turns on multi-volume. this FIXME: needs to be written into main body as well `--info-script=PROGRAM-FILE' Create a multi-volume archive via a script. FIXME: xref Multi-Volume Archives . `--interactive' Ask for confirmation before performing any operation on a file or archive member. `--keep-old-files' Prevent overwriting during extraction. FIXME: xref File Writing Options . `--label=ARCHIVE-LABEL' Include an archive-label in the archive being created. FIXME: xref Archive Label . `--modification-time' Set the modification time of extracted files to the time they were extracted. FIXME: xref File Writing Options . `--multi-volume' Specify a multi-volume archive. FIXME: xref Multi-Volume Archives . `--newer=DATE' Limit the operation to files changed after the given date. FIXME: xref File Exclusion . `--newer-mtime=DATE' Limit the operation to files modified after the given date. FIXME: xref File Exclusion . `--old' Create an old format archive. FIXME: xref Old Style File Information . FIXME: did we agree this should go away as a synonym? `--old-archive' Create an old format archive. FIXME: xref Old Style File Information . `--one-file-system' Prevent `tar' from crossing file system boundaries when archiving. FIXME: xref File Exclusion . `--portability' Create an old format archive. FIXME: xref Old Style File Information . FIXME: was portability, may still need to be changed `--preserve-order' Help process large lists of file names on machines with small amounts of memory. FIXME: xref Archive Reading Options . `--preserve-permission' Set modes of extracted files to those recorded in the archive. FIXME: xref File Writing Options . `--read-full-blocks' Read an archive with a smaller than specified block size or which contains incomplete blocks. FIXME: xref Archive Reading Options ). FIXME: should be --partial-blocks (!) `--record-number' Print the record number where a message is generated. FIXME: xref Additional Information . `--same-order' Help process large lists of file names on machines with small amounts of memory. FIXME: xref Archive Reading Options . `--same-permission' Set the modes of extracted files to those recorded in the archive. FIXME: xref File Writing Options . `--sparse' Archive sparse files sparsely. FIXME: xref Sparse Files . `--starting-file=FILE NAME' Begin reading in the middle of an archive. FIXME: xref Scarce Disk Space . `--to-stdout' Write files to the standard output. FIXME: xref File Writing Options . `--uncompress' Specifdo a compressed archive. FIXME: xref Compressed Archives . `-V ARCHIVE-LABEL' Include an archive-label in the archive being created. FIXME: xref Archive Label . FIXME: was --volume `--verbose' Print the names of files or archive members as they are being operated on. FIXME: xref Additional Information . `--verify' Check for discrepancies in the archive immediately after it is written. FIXME: xref Write Verification . Read an archive with a smaller than specified block size or which contains incomplete blocks. FIXME: xref Archive Reading Options ). `-K FILE NAME' Begin reading in the middle of an archive. FIXME: xref Scarce Disk Space . Specify a multi-volume archive. FIXME: xref Multi-Volume Archives . `-N DATE' Limit operation to files changed after the given date. FIXME: xref File Exclusion . Write files to the standard output. FIXME: xref File Writing Options . FIXME: - P is absolute names, add when resolved. Print the record number where a message is generated. FIXME: xref Additional Information . Archive sparse files sparsely. FIXME: xref Sparse Files . `-T FILE' Read file name arguments from a file on the file system. FIXME: xref File Name Lists . Check for discrepancies in the archive immediately after it is written. FIXME: xref Write Verification . Specify a compressed archive. FIXME: xref Compressed Archives . `-b NUMBER' Specify the blocking factor of an archive. FIXME: xref Blocking Factor . `-f ARCHIVE-NAME' Name the archive. FIXME: xref Archive Name ). Treat a symbolic link as an alternate name for the file the link points to. FIXME: xref Symbolic Links . Ignore end-of-archive entries. FIXME: xref Archive Reading Options . Prevent overwriting during extraction. FIXME: xref File Writing Options . Prevent `tar' from crossing file system boundaries when archiving. FIXME: xref File Exclusion . Set the modification time of extracted files to the time they were extracted. FIXME: xref File Writing Options . Create an old format archive. FIXME: xref Old Style File Information . Set the modes of extracted files to those recorded in the archive. FIXME: xref File Writing Options . Help process large lists of file names on machines with small amounts of memory. FIXME: xref Archive Reading Options . Print the names of files or archive members they are being operated on. FIXME: xref Additional Information . FIXME: see --interactive. Specify a compressed archive. FIXME: xref Compressed Archives . `-z -z' Create a whole block sized compressed archive. FIXME: xref Compressed Archives . FIXME: I would rather this were -Z. it is the only double letter short FIXME: form. `-C `directory'' Change the working directory. FIXME: xref Changing Working Directory . `-F PROGRAM-FILE' Create a multi-volume archive via a script. FIXME: xref Multi-Volume Archives . `-X `file'' Exclude files which match any of the regular expressions listed in the file `file'. FIXME: xref File Exclusion . * Menu: * Device Options:: * Blocking Options:: * Classification Options:: File: tar.info, Node: Device Options, Next: Blocking Options, Prev: Options, Up: Options Device selection and switching ------------------------------ *(This message will disappear, once this node revised.)* `-f [HOSTNAME:]FILE' `--file=[HOSTNAME:]FILE' Use archive file or device FILE on HOSTNAME. FIXME: xref Device . `--force-local' Archive file is local even if it contains a colon. FIXME: xref Device . `--rsh-command=COMMAND' Use remote COMMAND instead of `rsh'. FIXME: xref Device . `-[0-7][lmh]' Specify drive and density. FIXME: xref Device . `--multi-volume' Create/list/extract multi-volume archive. FIXME: xref Multi . `-L NUM' `--tape-length=NUM' Change tape after writing NUM x 1024 bytes. FIXME: xref Multi . `-F FILE' `--info-script=FILE' `--new-volume-script=FILE' Execute `file' at end of each tape. This implies `--multi-volume' (`-M')). FIXME: xref Multi . File: tar.info, Node: Blocking Options, Next: Classification Options, Prev: Device Options, Up: Options Device blocking --------------- *(This message will disappear, once this node revised.)* `-b BLOCKS' `--block-size=BLOCKS' Set block size to BLOCKS * 512 bytes. FIXME: xref Blocking . `--block-compress' Block the output of compression for tapes. FIXME: xref Blocking . `--ignore-zeros' Ignore blocks of zeros in archive (means EOF). FIXME: xref Blocking . `--read-full-blocks' Reblock as we read (for reading 4.2BSD pipes). FIXME: xref Blocking . File: tar.info, Node: Classification Options, Prev: Blocking Options, Up: Options Old classification of options ----------------------------- *(This message will disappear, once this node revised.)* The information here is to be revised and merged into the remainder of this document, possibly altering its structure. Options could be regrouped in three categories: General Options Options that are always meaningful. Creation Options Options for creating or updating an archive. Extraction Options Options for listing or extracting files. Here are the options that are always meaningful. `-B NUMBER', `--block-size NUMBER' `-f FILENAME', `--file FILENAME' `-C DIR', `--directory DIR' `-M', `--multi-volume' `-N DATE', `--after-date DATE' `-R', `--record-number' (`-R') `-T FILENAME', `--files-from FILENAME' `-v', `--verbose' (`-v') `-w', `--interactive' `-X FILE', `--exclude FILE' `-z', `-Z', `--compress', `--uncompress' Here are the options for creating or updating an archive. These options are used to control which files `tar' puts in an archive, or to control the format the archive is written in FIXME: ref Format . Except as noted elsewhere, these options are useful with the `--create' (`-c'), `--append' (`-r'), `--update' (`-u'), `--concatenate' (`-A'), and `--delete' commands. Also note that the {No Value For "read-full-block"} option FIXME: (pxref Extraction Options), is also useful with the `--append' (`-r'), `--update' (`-u'), `--concatenate' (`-A'), and `--delete' commands. `-G', `--incremental' `-h', `--dereference' (`-h') `-l', `--one-file-system' `-o', `--old-archive' (`-o') `--old', `--portability' `-S', `--sparse' `-V NAME', `--volume NAME' `-W', `--verify' Here are the options for listing or extracting files. The options in this section are meaningful with the `--extract' (`-x') command. Unless otherwise stated, they are also meaningful with the `--list' (`-t') command. `-B', `--read-full-blocks' `-G', `--incremental' `-i', `--ignore-zeros' `-k', `--keep-old-files' `-K FILENAME', `--starting-file FILENAME' `-m', `--modification-time' `-O', `--to-stdout' `-p', `--same-permissions', `--preserve-permissions' `-P', `--absolute-names' (`-P') `-s', `--same-order', `--preserve-order' `--preserve' File: tar.info, Node: Basic tar Operations, Next: Specifying Names to tar, Prev: Invoking tar, Up: Top Basic `tar' Operations ********************** *(This message will disappear, once this node revised.)* This chapter describes the basic operations supported by the `tar' program. A given invocation of `tar' will do exactly one of these operations. An archive member in normally extracted into a file with the same name as the archive member. However, you can use the `--to-stdout' (`-O') to cause `tar' to write extracted archive members to standard output. If you extract multiple members, they appear on standard output concatenated, in the order they are found in the archive. The `--create' (`-c') operation writes a new archive, and the `--extract' (`-x') operation reads files from an archive and writes them into the file system. You can use other `tar' operations to write new information into an existing archive (adding files to it, adding another archive to it, or deleting files from it), and you can read a list of the files in an archive without extracting it using the `--list' (`-t') operation. The primary argument to `tar' is the "operation", which specifies what `tar' does. `tar' can be used to: * Add files to an existing archive--`--append' (`-r'). * Compare files in an archive with files in the file system--`--compare' (`-d') or `--diff'. * Add archives to another archive--`--concatenate' (`-A'). * Create an archive--`--create' (`-c'). * Delete files from an archive--`--delete'. * Extract files from an archive--`--extract' (`-x') or `--get'. * List the files in an archive--`--list' (`-t'). * Update an archive by appending newer versions of already stored files--`--update' (`-u'). FIXME: xref Reading and Writing , for more information about these operations. "Option" arguments to `tar' change details of the operation, such as archive format, archive name, or level of user interaction. You can specify more than one option. All options are optional. "File Name" arguments specify which files (including directory files) to archive, extract, delete or otherwise operate on. If you don't use any file name arguments, `--append' (`-r'), `--update' (`-u') and `--delete' will do nothing. The other operations of `tar' will act on defaults. When you use a file name argument to specify a directory file, `tar' acts on all the files in that directory, including sub-directories. You must give exactly one option from the following list to `tar'. This option specifies the basic operation for `tar' to perform. `--create' Create a new archive `--catenate' `--concatenate' Add the contents of one or more archives to another archive `--append' Add files to an existing archive `--list' List the members in an archive `--delete' Delete members from an archive `--extract' `--get' Extract members from an archive `--compare' `--diff' Compare members in an archive with files in the file system `--update' Update an archive by appending newer versions of already stored files The remaining options to `tar' change details of the operation, such as archive format, archive name, or level of user interaction. You can specify more than one option. The remaining arguments are interpreted either as file names or as member names, depending on the basic operation `tar' is performing. For `--append' (`-r') and `--create' (`-c') these arguments specify the names of files (which must already exist) to place in the archive. For the remaining operation types, the additional arguments specify archive members to compare, delete, extract, list, or update. When naming archive members, you must give the exact name of the member in the archive, as it is printed by `--list' (`-t'). When naming files, the normal file name rules apply. If you don't use any additional arguments, `--append' (`-r'), `--concatenate' (`-A'), and `--delete' will do nothing. Naturally, `--create' (`-c') will make an empty archive if given no files to add. The other operations of `tar' (`--list' (`-t'), `--extract' (`-x'), `--compare' (`-d'), and `--update' (`-u')) will act on the entire contents of the archive. If you give the name of a directory as either a file name or a member name, then `tar' acts recursively on all the files and directories beneath that directory. For example, the name `/' identifies all the files in the filesystem to `tar'. The operation argument to `tar' specifies which action you want to take. Adds copies of an archive or archives to the end of another archive. Creates a new archive. Compares files in the archive with their counterparts in the file system, and reports differences in file size, mode, owner, modification date and contents. Adds files to the end of the archive. Prints a list of the contents of the archive. Reads files from the archive and writes them into the active file system. Adds files to the end of the archive, but only if they are newer than their counterparts already in the archive, or if they do not already exist in the archive. `--catenate' Adds copies of an archive or archives to the end of another archive. `--append' Adds files to the end of the archive. `--append' Adds files to the end of the archive. `--catenate' Adds copies of an archive or archives to the end of another archive. `--compare' Compares files in the archive with their counterparts in the file system, and reports differences in file size, mode, owner, modification date and contents. `--concatenate' Adds copies of an archive or archives to the end of another archive. `--create' Creates a new archive. `--delete' Deletes files from the archive. All versions of the files are deleted. `--diff' Compares files in the archive with their counterparts in the file system, and reports differences in file size, mode, owner, modification date and contents. `--extract' Reads files from the archive and writes them into the active file system. `--get' Reads files from the archive and writes them into the active file system. `--list' Prints a list of the contents of the archive. `--update' Adds files to the end of the archive, but only if they are newer than their counterparts already in the archive, or if they do not already exist in the archive. `--version' Prints the version number of the `tar' program to the standard error. The program `tar' can create an archive, extract files from an archive, modify an archive, or list an archive's contents. Each time you run `tar', you must give a "command" to specify which one of these things you want to do. The command must always be in the first argument to `tar'. This argument can also contain options ( FIXME: pxref Invoking tar ). For compatibility with Unix `tar', the first argument is always treated as containing command and option letters even if it doesn't start with `-'. Thus, `tar c' is equivalent to `tar -c': both of them specify the `--create' (`-c') command to create an archive. In addition, a set of long-named options are provided which can be used instead of or intermixed with the single-letter flags. The long-named options are meant to be easy to remember and logical, while the single letter flags may not always be. Long-named options begin with `--'. Arguments after the first are either options, if they start with `-' or `--', or files to operate on. The file names that you give as arguments are the files that `tar' will act on--for example, they are the files to put in the archive, or the files to extract from it. If you don't give any file name arguments, the default depends on which command you used. Some commands use all relevant files; some commands have no default and will report an error if you don't specify files. If a file name argument actually names a directory, then that directory and all files and subdirectories (recursively) in it are used. Here is a list of the `tar' commands: `--create' Create a new archive. This command tells `tar' to create a new archive that contains the file(s) specified on the command line. If you don't specify files, all the files in the current directory are used. If the archive file already exists, it is overwritten; the old contents are lost. `--extract' `--get' Extract files from an archive. This command causes `tar' to extract the specified files from the archive. If no file names are given, all the files in the archive will be extracted. `--list' List the contents of an archive. This command causes `tar' to display a list of the files in the archive. If you specify file names, only the files that you specify will be mentioned (but each of them is mentioned only if it appears in the archive). `--diff' `--compare' Find differences between an archive and the corresponding online files. This command causes `tar' to compare the archive with the files in the file system. It will report differences in file size, mode, owner, and contents. If a file exists in the archive, but not in the file system, `tar' will report this. If you specify file names, those files are compared with the tape and they must all exist in the archive. If you don't specify files, all the files in the archive are compared. `--append' Append files to the end of an archive. This command causes `tar' to add the specified file(s) to the end of the archive. This assumes that the archive file already exists and is in the proper format (which probably means it was created previously with the `tar' program). If the archive is not in a format that `tar' understands, the results will be unpredictable. You must specify the files to be used; there is no default. `--update' Only append files newer than the version in an archive. This command causes `tar' to add the specified files to the end of the archive, like `--append' (`-r'), but only when a file doesn't already exist in the archive or is newer than the version in the archive (the last-modification time is compared). Adding files to the end of an archive can be very slow. You must specify the files to be used; there is no default. `--catenate' `--concatenate' Append existing archives to another archive. This command is used for concatenating several archive files into one big archive file. The files to operate on should all be archive files. They are all appended to the end of the archive file which `tar' works on. (The other files are not changed). You might be tempted to use `cat' for this, but it won't ordinarily work. A `tar' archive contains data which indicates the end of the archive, so appended material is ignored. This command works because it removes the end-of-archive markers from the middle of the result. `--delete' Delete from the archive (not on tapes!). This command causes `tar' to delete the specified files from the archive. This command is extremely slow. Warning: Use of this command on archives stored on magnetic tape may result in a scrambled archive. There is no safe way (except for completely re-writing the archive) to delete files from a magnetic tape. The program `tar' can create an archive, extract files from an archive, modify an archive, or list an archive's contents. Each time you run `tar', you must give a "command" to specify which one of these things you want to do. The command must always be in the first argument to `tar'. This argument can also contain options ( FIXME: pxref Invoking tar ). For compatibility with Unix `tar', the first argument is always treated as containing command and option letters even if it doesn't start with `-'. Thus, `tar c' is equivalent to `tar -c': both of them specify the `--create' (`-c') command to create an archive. In addition, a set of long-named options are provided which can be used instead of or intermixed with the single-letter flags. The long-named options are meant to be easy to remember and logical, while the single letter flags may not always be. Long-named options begin with `--'. Arguments after the first are either options, if they start with `-' or `--', or files to operate on. The file names that you give as arguments are the files that `tar' will act on--for example, they are the files to put in the archive, or the files to extract from it. If you don't give any file name arguments, the default depends on which command you used. Some commands use all relevant files; some commands have no default and will report an error if you don't specify files. If a file name argument actually names a directory, then that directory and all files and subdirectories (recursively) in it are used. Modifying Archives Once an archive is created, you can add new archive members to it, add the contents of another archive, add newer versions of members already stored, or delete archive members already stored. To find out what files are already stored in an archive, use `tar --list --file=ARCHIVE-NAME'. FIXME: xref Listing Contents * Menu: * Creating a New Archive:: * Adding to an Existing Archive:: * Updating an Archive:: * Combining Archives:: * Removing Archive Members:: * Listing Archive Members:: * Extracting Archive Members:: * Comparing Archives Members with Files:: * Matching Format Parameters:: File: tar.info, Node: Creating a New Archive, Next: Adding to an Existing Archive, Prev: Basic tar Operations, Up: Basic tar Operations Creating a New Archive ====================== *(This message will disappear, once this node revised.)* The `--create' (`-c') option causes `tar' to create a new archive. The files to be archived are then named on the command line. Each file will be added to the archive with a member name exactly the same as the name given on the command line. (When you give an absolute file name `tar' actually modifies it slightly, FIXME: ref Absolute Names .) If you list no files to be archived, then an empty archive is created. If there are two many files to conveniently list on the command line, you can list the names in a file, and `tar' will read that file. FIXME: xref Reading Names from a File If you name a directory, then `tar' will archive not only the directory, but all its contents, recursively. For example, if you name `/', then `tar' will archive the entire filesystem. Do not use the option to add files to an existing archive; it will delete the archive and write a new one. Use `--append' (`-r') instead. FIXME: xref Adding to an Existing Archive .) There are various ways of causing `tar' to skip over some files, and not archive them. FIXME: xref Specifying Names to tar FIXME: operations should probably have examples, not tables. To create an archive, use `--create' (`-c'). To name the archive, use `--file=ARCHIVE-NAME' in conjunction with the `--create' (`-c') operation ( FIXME: pxref Archive Name ). If you do not name the archive, `tar' uses the value of the environment variable `TAPE' as the file name for the archive, or, if that is not available, `tar' uses a default archive name, usually that for tape unit zero. FIXME: xref Archive Name , for more information about specifying an archive name. The following example creates an archive named `stooges', containing the files `larry', `moe' and `curley': tar --create --file=stooges larry moe curley If you specify a directory name as a file name argument, `tar' will archive all the files in that directory. The following example creates an archive named `hail/hail/fredonia', containing the contents of the directory `marx': tar --create --file=hail/hail/fredonia marx If you don't specify files to put in the archive, `tar' archives all the files in the working directory. The following example creates an archive named `home' containing all the files in the working directory: tar --create --file=home FIXME: xref File Name Lists , for other ways to specify files to archive. Note: In the example above, an archive containing all the files in the working directory is being written to the working directory. GNU `tar' stores files in the working directory in an archive which is itself in the working directory without falling into an infinite loop. Other versions of `tar' may fall into this trap. File: tar.info, Node: Adding to an Existing Archive, Next: Updating an Archive, Prev: Creating a New Archive, Up: Basic tar Operations Adding to an Existing Archive ============================= *(This message will disappear, once this node revised.)* The `--append' (`-r') option will case `tar' to add new files to an existing archive. It interprets file names and member names in exactly the same manner as `--create' (`-c'). Nothing happens if you don't list any names. This option never deletes members. If a new member is added under the same name as an existing member, then both will be in the archive, with the new member after the old one. For information on how this affects reading the archive, FIXME: ref Multiple Members with the Same Name This operation cannot be performed on some tape drives, unfortunately, due to deficiencies in the formats thoes tape drives use. To add files to an archive, use `--append' (`-r'). The archive to be added to must already exist and be in proper archive format (which normally means it was created previously using `tar'). If the archive was created with a different block size than now specified, `tar' will report an error ( FIXME: pxref Blocking Factor ). If the archive is not a valid `tar' archive, the results will be unpredictable. You cannot add files to a compressed archive, however you can add files to the last volume of a multi-volume archive. FIXME: xref Matching Format Parameters The following example adds the file `shemp' to the archive `stooges' created above: tar --append --file=stooges shemp You must specify the files to be added; there is no default. `--update' (`-u') acts like `--append' (`-r'), but does not add files to the archive if there is already a file entry with that name in the archive that has the same modification time. Both `--update' (`-u') and `--append' (`-r') work by adding to the end of the archive. When you extract a file from the archive, only the version stored last will wind up in the file system. Because `--extract' (`-x') extracts files from an archive in sequence, and overwrites files with the same name in the file system, if a file name appears more than once in an archive the last version of the file will overwrite the previous versions which have just been extracted. You should avoid storing older versions of a file later in the archive. Note: `--update' (`-u') is not suitable for performing backups, because it doesn't change directory content entries, and because it lengthens the archive every time it is used. FIXME: xref to scripted backup, listed incremental, for info on backups. File: tar.info, Node: Updating an Archive, Next: Combining Archives, Prev: Adding to an Existing Archive, Up: Basic tar Operations Updating an Archive =================== *(This message will disappear, once this node revised.)* The `--update' (`-u') option updates a `tar' archive by comparing the date of the specified archive members against the date of the file with the same name. If the file has been modified more recently than the archive member, then the archive member is deleted (as with `--delete') and then the file is added to the archive (as with `--append' (`-r')). On media where the `--delete' option cannot be performed (such as magnetic tapes), the `--update' (`-u') option similarly fails. If no archive members are named (either on the command line or via `--files-from=FILE-OF-NAMES' (`-T FILE-OF-NAMES')), then the entire archive is processed in this manner. File: tar.info, Node: Combining Archives, Next: Removing Archive Members, Prev: Updating an Archive, Up: Basic tar Operations Combining Archives ================== *(This message will disappear, once this node revised.)* The `--concatenate' (`-A') or {No Value For "catenate"} option causes `tar' to add the contents of several archives to an existing archive. Name the archives to be catenated on the command line. (Nothing happens if you don't list any.) The members, and their member names, will be copied verbatim from those archives. If this causes multiple members to have the same name, it does not delete either; all the members with the same name coexist. For information on how this affects reading the archive, FIXME: ref Multiple Members with the Same Name You must use this option to concatenate archives. If you just combine them with `cat', the result will not be a valid `tar' format archive. This operation cannot be performed on some tape drives, unfortunately, due to deficiencies in the formats thoes tape drives use. To append copies of an archive or archives to the end of another archive, use `--concatenate' (`-A'). The source and target archives must already exist and have been created using compatable format parameters ( FIXME: pxref Matching Format Parameters ). `tar' will stop reading an archive if it encounters an end-of-archive marker. The `cat' utility does not remove end-of-archive markers, and is therefore unsuitable for concatenating archives. `--concatenate' (`-A') removes the end-of-archive marker from the target archive before each new archive is appended. FIXME: xref ignore-zeros You must specify the source archives using `--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME') ( FIXME: pxref Archive ). If you do not specify the target archive , `tar' uses the value of the environment variable `TAPE', or, if this has not been set, the default archive name. The following example adds the contents of the archive `hail/hail/fredonia' to the archive `stooges' (both archives were created in examples above): tar --catenate --file=stooges hail/hail/fredonia If you need to retrieve files from an archive that was added to using the `cat' utility, use the `--ignore-zeros' (`-i') option ( FIXME: pxref Archive Reading Options ). File: tar.info, Node: Removing Archive Members, Next: Listing Archive Members, Prev: Combining Archives, Up: Basic tar Operations Removing Archive Members ======================== *(This message will disappear, once this node revised.)* You can use the `--delete' option to remove members from an archive. Name the members on the command line to be deleted. This option will rewrite the archive; because of this, it does not work on tape drives. If you list no members to be deleted, nothing happens. To delete archive members from an archive, use `--delete'. You must specify the file names of the members to be deleted. All archive members with the specified file names will be removed from the archive. The following example removes the file `curley' from the archive `stooges': tar --delete --file=stooges curley You can only use `--delete' on an archive if the archive device allows you to write to any point on the media. *Warning:* Don't try to delete an archive member from a magnetic tape, lest you scramble the archive. There is no safe way (except by completely re-writing the archive) to delete files from most kinds of magnetic tape. FIXME: how about automatic detection of archive media? give error FIXME: unless the archive device is either an ordinary file or different FIXME: input and output (--file=-). File: tar.info, Node: Listing Archive Members, Next: Extracting Archive Members, Prev: Removing Archive Members, Up: Basic tar Operations Listing Archive Members ======================= *(This message will disappear, once this node revised.)* The `--list' (`-t') option will list the names of members of the archive. Name the members to be listed on the command line (to modify the way these names are interpreted, FIXME: pxref Specifying Names to ). If you name no members, then `--list' (`-t') will list the names of all the members of the archive. To see more than just the names of the members, use the `--verbose' (`-v') option to cause `tar' to print out a listing similar to that of `ls -l'. Listing the Contents of an Archive `--list' (`-t') prints a list of the file names of the archive members on the standard output. If you specify FILE NAME arguments on the command line (or using the `--files-from=FILE-OF-NAMES' (`-T FILE-OF-NAMES') option, FIXME: pxref File Name Lists ), only the files you specify will be listed, and only if they exist in the archive. Files not specified will be ignored, unless they are under a specific directory. If you include the `--verbose' (`-v') option, `tar' prints an `ls -l' type listing for the archive. FIXME: pxref Additional Information , for a description of the `--verbose' (`-v') option. If the blocking factor of the archive differs from the default, `tar' reports this. FIXME: xref Blocking Factor FIXME: xref Archive Reading Options for a list of options which can be used to modify `--list' (`-t')'s operation. This example prints a list of the archive members of the archive `stooges': tar --list --file=stooges `tar' responds: larry moe shemp marx/julius marx/alexander marx/karl This example generates a verbose list of the archive members of the archive file `dwarves', which has a blocking factor of two: tar --list -v --file=blocks `tar' responds: tar: Blocksize = 2 records -rw------- ringo/user 42 May 1 13:29 1990 .bashful -rw-rw-rw- ringo/user 42 Oct 4 13:29 1990 doc -rw-rw-rw- ringo/user 42 Jul 20 18:01 1969 dopey -rw-rw---- ringo/user 42 Nov 26 13:42 1963 grumpy -rw-rw-rw- ringo/user 42 May 5 13:29 1990 happy -rw-rw-rw- ringo/user 42 May 1 12:00 1868 sleepy -rw-rw-rw- ringo/user 42 Jul 4 17:29 1776 sneezy File: tar.info, Node: Extracting Archive Members, Next: Comparing Archives Members with Files, Prev: Listing Archive Members, Up: Basic tar Operations Extracting Archive Members ========================== *(This message will disappear, once this node revised.)* Use `--extract' (`-x') or `--get' to extract members from an archive. For each member named (or for the entire archive if no members are named) on the command line--or with `--files-from=FILE-OF-NAMES' (`-T FILE-OF-NAMES')--the a file is created with the contents of the archive member. The name of the file is the same as the member name. Various options cause `tar' to extract more than just file contents, such as the owner, the permissions, the modification date, and so forth. FIXME: begin The `--same-permissions' (`-p') or `--preserve-permissions' options cause `tar' to cause the new file to have the same permissions as the original file did when it was placed in the archive. Without this option, the current `umask' is used to affect the permissions. When extrating, `tar' normally sets the modification time of the file to the value recorded in the archive. The `--modification-time' (`-m') option causes `tar' to omit doing this. FIXME: end To read archive members from the archive and write them into the file system, use `--extract' (`-x'). The archive itself is left unchanged. If you do not specify the files to extract, `tar' extracts all the files in the archive. If you specify the name of a directory as a file name argument, `tar' will extract all files which have been stored as part of that directory. If a file was stored with a directory name as part of its file name, and that directory does not exist under the working directory when the file is extracted, `tar' will create the directory. FIXME: xref Selecting Archive Members , for information on specifying files to extract. The following example shows the extraction of the archive `stooges' into an empty directory: tar --extract --file=stooges Generating a listing of the directory (`ls') produces: larry moe shemp marx The subdirectory `marx' contains the files `julius', `alexander' and `karl'. If you wanted to just extract the files in the subdirectory `marx', you could specify that directory as a file name argument in conjunction with the `--extract' (`-x') operation: tar --extract --file=stooges marx *Warning:* Extraction can overwrite files in the file system. To avoid losing files in the file system when extracting files from the archive with the same name, use the `--keep-old-files' (`-k') option ( FIXME: pxref File Writing Options ). If the archive was created using `--block-size=512-SIZE' (`-b 512-SIZE'), `--compress' (`-Z') or `--multi-volume' (`-M'), you must specify those format options again when extracting files from the archive ( FIXME: pxref Format Variations ). * Menu: * Archive Reading Options:: * File Writing Options:: * Scarce Disk Space::