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: Top, Next: Introduction, Prev: (dir), Up: (dir) GNU tar ******* This file documents `tar', a utility used to store, backup, and transport files. It is a rudimentary documentation for the GNU tape (or disk) archiver. It covers the release 1.11.8. This document has been quickly assembled from random notes and sources. I will of course accept documentation bug reports, but please do not torture yourself into systematically reporting all inadequacies for unrevised nodes. * Menu: * Introduction:: * Tutorial:: * Invoking tar:: * Basic tar Operations:: * Specifying Names to tar:: * Being Careful:: * Format Control:: * Media:: * Backups and Restoration:: * Date input formats:: * Archive Format:: * Index:: -- The Detailed Node Listing -- Introduction * What tar Does:: * Authors:: * Bug reports:: * Support:: Support considerations * Stability:: * Rewriting:: * Why maintaining:: * MSDOS:: Tutorial Introduction to `tar' * How to Create Archives:: * How to List Archives:: * How to Extract Members from an Archive:: * How to Add Files to Existing Archives:: * How to Delete Members from Archives:: How to Create Archives * Creating Archives of Files bis:: * Using tar in Verbose Mode bis:: * How to Archive Directories:: * Creating an Archive of a Subdirectory bis:: * Compare bis:: * Using Compare from the Superior Directory bis:: How to Archive Directories * Creating an Archive of a Subdirectory bis:: How to List Archives * Listing files in an archive bis:: * Getting Additional File Information bis:: * List A Specific File in an Archive bis:: * Listing the Contents of a Stored Directory ter:: How to Extract Members from an Archive * Extracting Files bis:: * Extracting Files from an Archive ter:: * Extracting Specific Files ter:: * Extracting Directories ter:: How to Add Files to Existing Archives * Append bis:: * Update bis:: * Concatenate bis:: Invoking GNU `tar' * Synopsis:: * Option Styles:: * Options:: Many Styles for Options * Mnemonic Options:: * Short Options:: * Old Options:: * Mixing Styles:: All Available Options * Device Options:: * Blocking Options:: * Classification Options:: Basic `tar' Operations * 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:: Extracting Archive Members * Archive Reading Options:: * File Writing Options:: * Scarce Disk Space:: Specifying Names to `tar' * Changing the Archive Name:: * Characteristics:: * Selection Options:: Selecting Files by Characteristic * Reading Names from a File:: * Excluding Some Files:: * Operating Only on New Files:: * Crossing Filesystem Boundaries:: Local file selection * Changing Directory:: * Absolute File Names:: Being Even More Careful * Documentation:: * Checking Progress:: * Interactive Operation:: * Write Verification:: * Comparing:: * Portability:: * Write Protection:: Making `tar' Archives More Portable * Portable Names:: * Symbolic Links:: * Old V7 and POSIX:: * Checksumming Problems:: Controlling the Archive Format * Attributes Options:: * Type Options:: * Compression:: * Special Options for Archiving:: * Archive Structure:: * Modifiers Options:: Using Less Space through Compression * Compressed Archives:: * Dealing with Compressed Archives:: * Sparse Files:: Tapes and Other Archive Media * Device:: * Blocking:: * Many:: * Using Multiple Tapes:: * Archive Label:: Blocking * Format Variations:: * Blocking Factor:: Many archives on one tape * Tape Positioning:: * mt:: Using Multiple Tapes * Multi-Volume Archives:: * Tape Files:: Performing Backups and Restoring Files * Full Dumps:: * Inc Dumps:: * incremental and listed-incremental:: * Backup Levels:: * Backup Parameters:: * Scripted Backups:: * Scripted Restoration:: Setting Parameters for Backups and Restoration * backup-specs example:: * Script Syntax:: Date input formats * General date syntax:: * Calendar date item:: * Time of day item:: * Timezone item:: * Day of week item:: * Relative item in date strings:: * Pure numbers in date strings:: * Authors of getdate:: Format of `tar' archives * Standard:: * Extensions:: * cpio::  File: tar.info, Node: Introduction, Next: Tutorial, Prev: Top, Up: Top Introduction ************ This chapter introduces of a few words which will recur all over this manual, like "archive", "member", "name", "unpack", etc. It then explains who wrote GNU `tar' and its documentation, and says where to send bug reports or comments. * Menu: * What tar Does:: * Authors:: * Bug reports:: * Support::  File: tar.info, Node: What tar Does, Next: Authors, Prev: Introduction, Up: Introduction What `tar' Does =============== The `tar' program is used to create and manipulate `tar' archives. An "archive" is a single file which contains within it the contents of many files. In addition, the archive identifies the names of the files, their owner, and so forth. (Archives record access permissions, user and group, size in bytes, and last modification time. Some archives also record the file names in each archived directory, as well as other file and directory information.) The files inside an archive are called "members". Within this manual, we use the term "file" to refer only to files accessible in the normal ways (by `ls', `cat', and so forth), and the term "members" to refer only to the members of an archive. Similarly, a "file name" is the name of a file, as it resides in the filesystem, and a "member name" is the name of an archive member within the archive. Initially, `tar' archives were used to store files conveniently on magnetic tape. The name `tar' comes from this use; it stands for: `t'ape `ar'chiver. Despite the utility's name, `tar' can direct its output to any available device, as well as store it in a file or direct it to another program via a pipe. `tar' may even access, as archives, remote devices or files. You can use `tar' archives in many ways. We want to stress a few of them: storage, backup or transportation. Storage Often, `tar' archives are used to store related files for convenient file transfer over a network. For example, the GNU Project distributes its software bundled into `tar' archives, so that all the files relating to a particular program (or set of related programs) can be transferred as a single unit. A magnetic tape can store several files in sequence, but has no names for them, just relative position on the tape. A `tar' archive or something like it is one way to store several files on one tape and retain their names. Even when the basic transfer mechanism can keep track of names, as FTP can, the nuisance of handling multiple files, directories, and multiple links, makes `tar' archives an attractive method. Archive files are also used for long-term storage, which you can think of as transportation from one time to another. Backup Because the archive created by `tar' is capable of preserving file information and directory structure, `tar' is commonly used for performing full and incremental backups of disks, putting all together bunch of files possibly pertaining to many users and different projects, to secure against accidental destruction of those disks. The GNU version of `tar' has special features that allow it to be used to make incremental and full dumps of all the files in a filesystem. Transportation Archive files can be used for transporting a group of files from one system to another: put all relevant files into an archive on one computer system, transfer the archive to another, and extract the contents there. The basic transfer medium might be magnetic tape, Internet FTP, or even electronic mail (though you must encode the archive with `uuencode' or some functional equivalent in order to transport it properly by mail). Both machines do not have to use the same operating system, as long as they both support the `tar' program. Piping one `tar' to another is an easy way to copy a directory's contents from one disk to another, while preserving the dates, modes, owners and link structure of all the files therein. `tar' is also ideal for transferring directories over networks. We sometimes see a copy of `tar' packing many files into one archive on one machine, and sending the produced archive over a pipe over the network to another copy of `tar' on another machine, reading its archive from the pipe and unpacking all files there. The `tar' program provides the ability to create `tar' archives, as well as for various other kinds of manipulation. For example, you can use `tar' on previously created archives to extract files, to store additional files, or to update or list files already stored. The term "extraction" is used to refer to the process of copying an archive member into a file in the filesystem. One might speak of extracting a single member. Extracting all the members of an archive is often called extracting the archive. Also, the term "unpack" is used to refer to the extraction of many or all the members of an archive. Conventionally, `tar' archives are given names ending with `.tar'. This is not necessary for `tar' to operate properly, but this manual follows the convention in order to get the reader used to seeing it. Occasionally, `tar' archives are referred to as `tar' files, archive members are referred to as files, or entries. For people familiar with the operation of `tar', this causes no difficulty. However, this manual consistently uses the terminology above in referring to archives and archive members, to make it easier to learn how to use `tar'.  File: tar.info, Node: Authors, Next: Bug reports, Prev: What tar Does, Up: Introduction GNU `tar' Authors ================= GNU `tar' was originally written by John Gilmore, and modified by many people. The GNU enhancements were written by Jay Fenlason, and the whole package has been further maintained by Michael Bushnell, then Franc,ois Pinard, with the help of numerous and kind users. I wish to stress that `tar' is somewhat a collective work, and owe much to all those people who reported problems, offerred solutions and other insights, or shared their thoughts and suggestions. Even if we lost track of many of those contributors, a partial list can be found in the `THANKS' file from the GNU `tar' distribution. Jay Fenlason put together a draft of a GNU `tar' manual, also borrowing notes from the original man page from John Gilmore, this draft has been distributed in `tar' versions 1.04 (or even before?) through 1.10, then withdrawn in version 1.11. Michael Bushnell and Amy Gorin worked at a tutorial and manual for GNU `tar', and left a few unpublished versions of each. For version 1.11.8, Franc,ois Pinard put together a new manual by grabbing from all these sources and merging them in a single manual. I heard that there is another manual in the works, by another team, which should say everything about archives and related utilities, and which will surely be nicer than this one. In the meantime, please consider this manual is a placeholder for `tar' option list and a few random notes the maintainer wants to save somewhere, so users can read them. I wish GNU `tar' users will be happier with this imperfect manual than with no documentation at all.  File: tar.info, Node: Bug reports, Next: Support, Prev: Authors, Up: Introduction Reporting bugs or suggestions ============================= Please report problems or suggestions about this program to `bug-gnu-utils@prep.ai.mit.edu'. You may also write directly, and less officially, to `pinard@iro.umontreal.ca'. There is a lot of mail flowing about `tar', and some accumulated in the past years. You might expect a quick acknowledgement of your invoices, but the proper handling of your reports may be delayed for a long while. Many nodes of this document have not been revised much, these all start with a little comment telling so. I accept documentation bug reports, of course. But please do not torture yourself into systematically reporting all inadequacies for the unrevised nodes of this document, unless you really feel like revising them.  File: tar.info, Node: Support, Prev: Bug reports, Up: Introduction Support considerations ====================== This informal appendix is for the maintainer to share a few words and thoughts, while considering GNU `tar' support. * Menu: * Stability:: * Rewriting:: * Why maintaining:: * MSDOS::  File: tar.info, Node: Stability, Next: Rewriting, Prev: Support, Up: Support Stability of GNU `tar' ---------------------- User reports mainly fall in three categories: portability problems, execution bugs, and requests for enhancements. For 1.11.X, the emphasis has been on solving portability problems, then trying to make GNU `tar' more solid. Enhancements have fairly low priority, yet I sometime slip one in just for taking a kind of rest :-). Many bugs have been corrected since 1.11.2. If you are curious, glance through ChangeLog. I had only very few reports for things that *might* be new bugs not present in 1.11.2. If you are really curious, and have access to the FSF machines, see `/gd/gnu/tar/rmail/' hierarchy for all reports. Subdirectories `0', `1', `2' and `3' represent decreasing levels in priority. Most problems in there were reported against 1.10, 1.11 or 1.11.2 and still exist. The only thing I have consciously broken between 1.11.2 and 1.11.5 is `--record-number' (`-R'), because I wanted some modification to be done to `gnulib/error.c', which is outside my control. This modification is now done, but I did not revisit this area yet. Here is my candid opinion. GNU `tar' has many areas of unreliability. See `BACKLOG' for the horrorful picture of the situation. Yet, for most users and usages, GNU `tar' looks very dependable. For me as a mere user, GNU `tar' did not give problems in years. And I think it offers a lot of functionality. Many problems have been solved since 1.11.2, even if true that many more remain to be solved. I'm not discouraged myself and feel positive about maintaining it, simply because when I bite, that usually lasts for quite long. I might not have all the time I would want, but I surely have good will and am happily surrounded by many collaborating pretesters. So, I still think GNU `tar' is on the winning side in the long run.  File: tar.info, Node: Rewriting, Next: Why maintaining, Prev: Stability, Up: Support Should we rewrite the thing? ---------------------------- Working in `tar' sources is not always pleasurable. The problem is that `tar' sources are very fragile. Just cleaning around breaks things. The current sequence of prereleases is for slowly trying to solidify it, so `tar' becomes more maintainable. I think that the ugliness of sources could be corrected to a certain extent, too. A few efforts to replace GNU `tar' have been done already and it seems that all failed so far. A toy program, for me, is another kind of failure. I think people underestimate the number of portability problems such a program can raise. This is not only a matter of programming style, there is really a wide variability in systems out there. GNU `tar' has a long history, met a rich variety of porting problems, machine peculiarities, system idiosyncrasies, which are unrelated to programming style. My own opinion is that we cannot dismiss all the experience gleaned along the years, and saved (if not hidden) in GNU `tar' sources, pretending to start anew, from scratch. Even if a new program replacing GNU `tar' would be marvelous, GNU `tar' stalled for a few years waiting for such a program, and we are now faced to nothing, with hundreds of user reports to catch on. We need a working archiver *now*, and cannot live on promises. Any new program will take hundreds of user reports, and many years, to stabilize enough to become a plausible `tar' replacement. I rather plan to clean up GNU `tar'. This alone is a big task for me, because GNU `tar' coding is not ideal, and I have to find ways to transform it slowly, while having it fully working at all times.  File: tar.info, Node: Why maintaining, Next: MSDOS, Prev: Rewriting, Up: Support Why maintaining it? ------------------- I confess that I am a little afraid of `tar' maintainance. It is difficult for many reasons, the first tree being more evident than the others: * the algorithmic design was initially oriented for machines having very small memory, it was later much adapted for new features without doing everything necessary for the whole to stay clean; * the wide visibility of `tar' forces many stunts at portability; * GNU `tar' has to be sensitive to file systems and device variance. * GNU central has been seduced by some users promising to write wonderful `tar' replacements, which never came, so development has been put aside for years, while bug reports accumulated; * the `tar' manual has been withdrawn, promising users a fine replacement for it, so raising their expectations; * maintenance was once split between four maintainers (one for `tar', one for `mt', another for scripts, and a team for documentation), and also, `rtapelib.[ch]' from `tar' is used in `cpio', and synchronisation has not always been easy. However, even if difficult, I do feel like doing a careful cleanup, so `tar' would become less painful to maintain after a while (and less subject to criticism). And besides, I'm surrounded by a marvelous team of pretesters and by many other collaborating users, which I should learn to serve better. Getting more experience with maintainance in GNU, I hope being careful enough modifying `tar' so not hurting users too much, being aware that `tar' is a sensitive product in GNU. Once cleaned up, I might be happy to return `tar' maintainance to someone else... `tar' requires more work alone that all my other things together, and I have to resist being swallowed whole in it. This resistance makes `tar' development somewhat slower. Sorry!  File: tar.info, Node: MSDOS, Prev: Why maintaining, Up: Support MSDOS and other systems? ------------------------ GNU does not necessarily support non-UNIX systems, that is to say, MSDOS is not supported. It is very true that ports can sometimes be very intrusive in the sources, cluttering them significantly with conditionals and extra code, and distract GNU maintainers from the main development line. However, a special argument might be made for `tar'. Both `tar' and `gzip' are the required tools for getting something out of the GNU archives, `tar' should be more opened to ports than the GNU rule states. Jean-loup did a tremendous job at porting `gzip' on smaller systems. It would be comfortable that a few other GNU tools be available on MSDOS and others, among which `tar'. These ports for `tar' have theoretically no priority at all. Nevertheless, a port is interesting, because `tar' is so central in GNU distributions, and `gzip' is already ported. Some porting efforts have been done in the past. There are traces of a few exchanges on this subject in `BACKLOG'. GNU `tar' sources have been modified a lot recently at a cosmetic level, and I would certainly have a hard time integrating diffs provided by someone else. If people want porting `tar' to MSDOS or other non-UNIX systems, they should be committed in supporting their ports after the fact, as I cannot do it myself.  File: tar.info, Node: Tutorial, Next: Invoking tar, Prev: Introduction, Up: Top Tutorial Introduction to `tar' ****************************** This chapter guides you through some basic examples of `tar' operations. If you already know how to use some other version of `tar', then you probably don't need to read this chapter. This chapter omits complicated details about many of the ways `tar' works. See later chapters for full information. Before proceeding further with this tutorial chapter, be sure you understand already and clearly what is meant by "archive" and "archive member". FIXME: xref What tar Does . This chapter guides you through some basic examples of `tar' operations. In the examples, the lines you should type are preceded by a `%', which is a typical shell prompt. We use mnemonic forms of operations and options in the examples, and in discussions in the text, but short forms produce the same result. Most of the options to `tar' come in both long forms and short forms. The options described in this tutorial have the following abbreviations (except `--delete', which has no shorthand form): `--create' `-c' `--list' `-t' `--extract' `-x' `--append' `-r' `--verbose' `-v' `--file=ARCHIVE-NAME' `-f ARCHIVE-NAME' These options make typing long `tar' commands easier. For example, instead of typing tar --create --file=/tmp/afiles.tar --verbose apple angst asparagus you can type tar -c -f /tmp/afiles.tar -v apple angst asparagus For more information on option syntax, FIXME: ref Invoking tar . In discussions in the text, when we present some mnemonic option, we also give the corresponding short option within parentheses. * Menu: * How to Create Archives:: * How to List Archives:: * How to Extract Members from an Archive:: * How to Add Files to Existing Archives:: * How to Delete Members from Archives::  File: tar.info, Node: How to Create Archives, Next: How to List Archives, Prev: Tutorial, Up: Tutorial How to Create Archives ====================== *(This message will disappear, once this node revised.)* To create a new archive, use the `--create' (`-c') option to `tar'. You can use options to specify the name and format of the archive (as well as other characteristics), and you can use file name arguments to specify which files and directories are to be put in the archive. FIXME: xref Creating , for more information about the `--create' (`-c') operation. To create a new archive, use the `--create' (`-c') option to `tar'. You should generally use the `--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME') option to specify the name the `tar' archive will have. Then specify the names of the files you wish to place in the new archive. For example, to place the files `apple', `angst', and `asparagus' into an archive named `afiles.tar', use the following command: tar --create --file=afiles.tar apple angst asparagus The order of the arguments is not important when using mnemonic option style. You could also say: tar apple --create angst --file=afiles.tar asparagus This order is harder to understand however. In this manual, we will list the arguments in a reasonable order to make the commands easier to understand, but you can type them in any order you wish. If you don't specify the names of any files to put in the archive, then `tar' will create an empty archive. So, the following command will create an archive with nothing in it: tar --create --file=empty-archive.tar Whenever you use `--create' (`-c'), `tar' will erase the current contents of the file named by `--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME') if it exists. To add files to an existing archive, you need to use a different option. FIXME: xref Adding to Archives, for information on how to do this. When an archive is created through `--create' (`-c'), the member names of the members of the archive are exactly the same as the file names as you typed them in the `tar' command. So, the member names of `afiles' (as created by the first example above) are `apple', `angst', and `asparagus'. However, suppose an archive were created with this command: tar --create --file=bfiles.tar ./balloons baboon ./bodacious Then, the three files `balloons', `baboon', and `bodacious' would get placed in the archive (because `./' is a synonym for the current directory), but their member names would be `./balloons', `baboon', and `./bodacious'. If you want to see the progress of `tar' as it writes files into the archive, you can use the `--verbose' (`-v') option. If one of the files named with `--create' (`-c') is a directory, then the operation of `tar' is more complicated. FIXME: xref Tar and Directories, FIXME: the last section of this tutorial, for more information. If you don't specify the `--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME') option, then `tar' will use a default. Usually this default is some physical tape drive attached to your machine. If there is no tape drive attached, or the default is not meaningful, then `tar' will print an error message. This error message might look roughly like one of the following: tar: can't open /dev/rmt8 : No such device or address tar: can't open /dev/rsmt0 : I/O error If you get an error like this, mentioning a file you didn't specify (`/dev/rmt8' or `/dev/rsmt0' in the examples above), then `tar' is using a default value for `--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME'). You should generally specify a `--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME') argument whenever you use `tar', rather than relying on a default. To create a new archive, use the `--create' (`-c') option to `tar'. You can use options to specify the name and format of the archive (as well as other characteristics), and you can use file name arguments to specify which files to put in the archive. If you don't use any options or file name arguments, `tar' will use default values. FIXME: xref Creating Example , for more information about the `--create' (`-c') option. * Menu: * Creating Archives of Files bis:: * Using tar in Verbose Mode bis:: * How to Archive Directories:: * Creating an Archive of a Subdirectory bis:: * Compare bis:: * Using Compare from the Superior Directory bis::  File: tar.info, Node: Creating Archives of Files bis, Next: Using tar in Verbose Mode bis, Prev: How to Create Archives, Up: How to Create Archives Creating Archives of Files -------------------------- *(This message will disappear, once this node revised.)* This example shows you how to create an archive file in your working directory containing other files in the same directory. The three files you archive in this example are called `blues', `folk', and `jazz'. The archive file is called `records'. While the archive in this example is written to the file system, it could also be written to tape. (If you want to follow along with this and future examples, create a practice subdirectory containing files with these names. To create the directory, type `mkdir practice' at the system prompt. You can create the files using a text editor, such as `emacs'). While in the directory containing the files you want to archive, list the directory's contents. Type: % cd practice % ls The system responds: blues folk jazz % This is to check that the files to be archived do in fact exist in the working directory, and to check that the archive name you have chosen isn't already in use. If it is, `tar' will overwrite the old archive and its contents will be lost. Then, * Create a new archive by giving `--create' (`-c') to `tar'. * Explicitly name the archive file being created--`--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME'). If you don't use this option `tar' will write the archive to the default storage device, which varies from system to system. * Specify which files to put into the archive. If you don't specify any FILE NAME arguments, `tar' will archive everything in the working directory. Type: % tar --create --file=records blues folk jazz If you now list the contents of the working directory (`ls'), you will find the archive file listed as well as the files you saw previously. % ls blues folk jazz records % This example shows you how to create an archive file in the working directory containing other files in the working directory. The three files you archive in this example are called `blues', `folk', and `jazz'. The archive file is called `records'. While the archive in this example is written to the file system, it could also be written to any other device. (If you want to follow along with this and future examples, create a directory called `practice' containing files called `blues', `folk' and `jazz'. To create the directory, type `mkdir practice' at the system prompt. It will probably be easiest to create the files using a text editor, such as Emacs.) First, change into the directory containing the files you want to archive: % cd practice `~/practice' is now your working directory. Then, check that the files to be archived do in fact exist in the working directory, and make sure there isn't already a file in the working directory with the archive name you intend to use. If you specify an archive file name that is already in use, `tar' will overwrite the old file and its contents will be lost. To list the names of files in the working directory, type: % ls The system responds: blues folk jazz % Then, * Create a new archive by giving the `--create' (`-c') option to `tar'. * Explicitly name the archive file being created--`--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME'). If you don't use this option `tar' will write the archive to the default storage device, which varies from system to system. FIXME: this syntax may change. OK now--check before printing `tar' interprets archive file names relative to the working directory. Make sure you have write access to the working directory before using `tar'. * Specify which files to put into the archive (`tar' interprets file names relative to the working directory). If you don't use any NAME arguments, `tar' will archive everything in the working directory. Type: % tar --create --file=records blues folk jazz If you now list the contents of the working directory (`ls'), you will find the archive file listed as well as the files you saw previously. % ls blues folk jazz records %  File: tar.info, Node: Using tar in Verbose Mode bis, Next: How to Archive Directories, Prev: Creating Archives of Files bis, Up: How to Create Archives Using `tar' in Verbose Mode --------------------------- *(This message will disappear, once this node revised.)* If you include the `--verbose' (`-v') option on the command line, `tar' will list the files it is acting on as it is working. The example above in verbose mode would be: % tar --create --file=records --verbose blues folk jazz blues folk jazz The first line, which is preceeded by a `%', is the command line. The lines after the first line are generated by `tar' as it works. In the following examples we usually use verbose mode, though it is almost never required. If you include the `--verbose' (`-v') option on the command line, `tar' will list the files it is acting on as it is working. In verbose mode, the creation example above would appear as: % tar --create --file=records --verbose blues folk jazz blues folk jazz The first line is the command typed in by the user. The remaining lines are generated by `tar'. In the following examples we usually use verbose mode, though it is almost never required.  File: tar.info, Node: How to Archive Directories, Next: Creating an Archive of a Subdirectory bis, Prev: Using tar in Verbose Mode bis, Up: How to Create Archives How to Archive Directories -------------------------- *(This message will disappear, once this node revised.)* When the names of files or members specify directories, the operation of `tar' is more complex. Generally, when a directory is named, `tar' also operates on all the contents of the directory, recursively. Thus, to `tar', the file name `/' names the entire file system. To archive the entire contents of a directory, use `--create' (`-c') or `--append' (`-r') as usual, and specify the name of the directory. For example, to archive all the contents of the current directory, use `tar --create --file=ARCHIVE-NAME .'. Doing this will give the archive members names starting with `./'. To archive the contents of a directory named `foodir', use `tar --create --file=ARCHIVE-NAME foodir'. In this case, the member names will all start with `foodir/'. If you give `tar' a command such as `tar --create --file=foo.tar .', it will report `tar: foo.tar is the archive; not dumped'. This happens because the archive `foo.tar' is created before putting any files into it. Then, when `tar' attempts to add all the files in the directory `.' to the archive, it notices that the file `foo.tar' is the same as the archive, and skips it. (It makes no sense to put an archive into itself.) GNU `tar' will continue in this case, and create the archive as normal, except for the exclusion of that one file. Other versions of `tar', however, are not so clever, and will enter an infinite loop when this happens, so you should not depend on this behavior. In general, make sure that the archive is not inside a directory being dumped. When extracting files, you can also name directory archive members on the command line. In this case, `tar' extracts all the archive members whose names begin with the name of the directory. As usual, `tar' is not particularly clever about interpreting member names. The command `tar --extract --file=ARCHIVE-NAME .' will not extract all the contents of the archive, but only those members whose member names begin with `./'. * Menu: * Creating an Archive of a Subdirectory bis::  File: tar.info, Node: Creating an Archive of a Subdirectory bis, Next: Compare bis, Prev: How to Archive Directories, Up: How to Create Archives Creating an Archive from the Superior Directory ----------------------------------------------- *(This message will disappear, once this node revised.)* You can archive a directory by specifying its directory name as a file name argument to `tar'. The files in the directory will be archived relative to the working directory, and the directory will be re-created along with its contents when the archive is extracted. To archive a directory, first move to its superior directory. If you have been following the tutorial, you should type: % cd .. % Once in the superior directory, you can specify the subdirectory as a file name argument. To store the directory `practice' in the archive file `music', type: % tar --create --verbose --file=music practice `tar' should output: practice/ practice/blues practice/folk practice/jazz practice/records Note that the archive thus created is not in the subdirectory `practice', but rather in the working directory--the directory from which `tar' was invoked. Before trying to archive a directory from its superior directory, you should make sure you have write access to the superior directory itself, not only the directory you are trying archive with `tar'. Trying to store your home directory in an archive by invoking `tar' from the root directory will probably not work. FIXME: xref absolute-names (Note also that `records', the original archive file, has itself been archived. `tar' will accept any file as a file to be archived, regardless of its content. When `music' is extracted, the archive file `records' will be re-written into the file system). You can store a directory in an archive by using the directory name as a file name argument to `tar'. When you specify a directory file, `tar' archives the directory file and all the files it contains. The names of the directory and the files it contains are stored in the archive relative to the current working directory-when the directory is extracted they will be written into the file system relative to the working directory at that time. FIXME: add an xref to --absolute-names To archive a directory, first move to its superior directory. If you have been following the tutorial, you should type: % cd .. % Once in the superior directory, specify the subdirectory using a file name argument. To store the directory file `~/practice' in the archive file `music', type: % tar --create --verbose --file=music practice `tar' should respond: practice/ practice/blues practice/folk practice/jazz practice/records Note that `~/practice/records', another archive file, has itself been archived. `tar' will accept any file as a file to be archived, even an archive file. FIXME: symbolic links and changing directories are now in main body, FIXME: not in tutorial.  File: tar.info, Node: Compare bis, Next: Using Compare from the Superior Directory bis, Prev: Creating an Archive of a Subdirectory bis, Up: How to Create Archives Comparing Files in an Archive with Files in the File System ----------------------------------------------------------- *(This message will disappear, once this node revised.)* While the `--list' (`-t') operation with the `--verbose' (`-v') option specified is useful in keeping files in the archive current with files in the file system (by allowing the user to compare size and modification dates), it is simpler to have `tar' itself compare file attributes and report back on file differences. To do so, use the `--compare' (`-d') or `--diff' operation. The `--compare' (`-d') operation, as its name implies, causes `tar' to compare files and directories in the archive with their counterparts (files of the same name) in the file system, and report back differences in file size, mode, owner and modification date. When performing the `--compare' (`-d') operation, `tar' acts only on files actually in the archive--it will ignore files in the active file system that do not exist in the archive. If `tar' with `--compare' (`-d') specified is given, as a file name argument, the name of a file that does not exist in the archive, it will return an error message. To compare the files in the practice directory with their counterparts in the archive file `records', in the same directory, you would, while in the `practice' directory: * Invoke `tar' and specify the operation to compare files in the archive with their counterparts in the file system--`--compare' (`-d') or `--diff'. * Specify the name of the archive where the files to be compared are stored--`--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME'). * Specify the names of the files or directories to be compared, as file name arguments (in this case, you are comparing all the files in the archive, so nothing need be specified). % tar --compare --file=records % While it looks like nothing has happened, `tar' has, in fact, done the comparison--and found nothing to report. The same example with the `--verbose' (`-v') option specified would list the files in the archive as they are being compared with their counterparts of the same name: % tar --compare --verbose --file=records blues folk jazz % If `tar' had had anything to report, it would have done so as it was comparing each file. If you remove the file `jazz' from the file system (`rm jazz'), and modify the file `blues' (for instance, by adding text to it with a text editor), the above example would look like: % tar --compare --verbose --file=records blues blues: mod time differs blues: size differs folk jazz jazz: does not exist % You should note again that while `--compare' (`-d') does cause `tar' to report back on files in the archive that do not exist in the file system, `tar' will ignore files in the active file system that do not exist in the archive. To demonstrate this, create a file in the `practice' directory called `rock' (using any text editor). If you generate a directory listing the new file will appear. % ls blues folk records rock If you run the `--compare' (`-d') example again you will obtain the following: % tar --compare --verbose --file=records blues blues: mod time differs blues: size differs folk jazz jazz: does not exist % `tar' ignores the file `rock' because `tar' is comparing files in the archive to files in the file system, not vice versa. If `rock' had been passed to `tar' explicitly (as a file name argument), `tar' would have returned an error message, as follows: % tar --compare --verbose --file=records rock tar: rock not found in archive % To compare the attributes of archive members with the attributes of their counterparts in the file system, use the `--compare' (`-d') or `--diff'operation. While you could use `--list --verbose' (`-tv') to manually compare some file attributes, it is simpler to have `tar' itself compare file attributes and report back on file differences. FIXME: "manually"? suggestions? The `--compare' (`-d') operation, as its name implies, compares archive members with files of the same name in the file system, and reports back differences in file size, mode, owner and modification date. `tar +compare' acts only on archive members-it ignores files in the file system that are not stored in the archive. If you give with `--compare' (`-d') a NAME argument that does not correspond to the name of an archive member, `tar' responds with an error message. To compare archive members in the archive file `records' with files in the `~/practice' directory, first change into the `practice' directory. Then: * Invoke `tar' and specify the `--compare' (`-d') operation--`--compare' (`-d') or `--diff'. * Specify the archive where the files to be compared are stored--`--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME'). * Specify the archive members to be compared. (In this example you are comparing all the archive members in the archive. Since this is the default, you don't need to use any file name arguments). % tar --compare --file=records % While it looks like nothing has happened, `tar' has, in fact, done the comparison--and found nothing to report. Use the `--verbose' (`-v') option to list the names of archive members as they are being compared with their counterparts of the same name in the file system: % tar --compare --verbose --file=records blues folk jazz % If `tar' had had anything to report, it would have done so as it was comparing each file. If you remove the file `jazz' from the file system (`rm jazz'), and modify the file `blues' (for instance, by adding text to it with an editor such as Emacs), the above example would look like: % tar --compare --verbose --file=records blues blues: mod time differs blues: size differs folk jazz jazz: does not exist % Note again that while `--compare' (`-d') reports the names of archive members that do not have counterparts in the file system, `--compare' (`-d') ignores files in the file system that do not have counterparts in the archive. To demonstrate this, create a file in the `practice' directory called `rock' (using any text editor). The new file appears when you list the directory's contents: FIXME: Given an example  File: tar.info, Node: Using Compare from the Superior Directory bis, Prev: Compare bis, Up: How to Create Archives Using Compare from the Superior Directory ----------------------------------------- *(This message will disappear, once this node revised.)* In addition to using `--compare' (`-d') to compare individual files in an archive with their counterparts in the file system, you can use `--compare' (`-d') to compare archived directories with their counterparts in the active file system. You could re-create the examples above using your home directory as the working directory, and using the archive file `music' (in which is stored the `practice' directory) instead of the archive file `records'. First, change into the home directory (`cd ..'). Then, try the above example using `music' as the specified archive file, and the `practice' subdirectory as a file name argument. % tar --compare --verbose --file=music practice practice practice/blues practice/blues: mod time differs practice/blues: size differs practice/folk practice/jazz practice/jazz: does not exist practice/records In addition to using `--compare' (`-d') to compare text files, you can use `--compare' (`-d') to compare directories. To illustrate this, re-create the examples above using your home directory as the working directory, and using the archive file `~/music' instead of the archive file `~/practice/records'. First, change into your home directory (`cd ~'). Then, try the above example using `music' as the specified archive file, and `practice' as a file name argument. % tar --compare --verbose --file=music practice If you have been following along with the tutorial, `tar' will respond: practice practice/blues practice/blues: mod time differs practice/blues: size differs practice/folk practice/jazz practice/jazz: does not exist practice/records  File: tar.info, Node: How to List Archives, Next: How to Extract Members from an Archive, Prev: How to Create Archives, Up: Tutorial How to List Archives ==================== *(This message will disappear, once this node revised.)* Use `--list' (`-t') to print the names of members stored in an archive. Use a `--file=ARCHIVE-NAME' (`-f ARCHIVE-NAME') option just as with `--create' (`-c') to specify the name of the archive. For example, the archive `afiles.tar' created in the last section could be examined with the command `tar --list --file=afiles.tar'. The output of `tar' would then be: apple angst asparagus The archive `bfiles.tar' would list as follows: ./baloons baboon ./bodacious (Of course, `tar --list --file=empty-archive.tar' would produce no output.) If you use the `--verbose' (`-v') option with `--list' (`-t'), then `tar' will print out a listing reminiscent of `ls -l', showing owner, file size, and so forth. You can also specify member names when using `--list' (`-t'). In this case, `tar' will only list the names of members you identify. For example, `tar --list --file=afiles.tar apple' would only print `apple'. It is essential when specifying member names to `tar' that you give the exact member names. For example, `tar --list --file=bfiles baloons' would produce no output, because there is no member named `baloons', only one named `./baloons'. While the file names `baloons' and `./baloons' name the same file, member names are compared using a simplistic name comparison, in which an exact match is necessary. * Menu: * Listing files in an archive bis:: * Getting Additional File Information bis:: * List A Specific File in an Archive bis:: * Listing the Contents of a Stored Directory ter::