2.6 How to Create Archives

One of the basic operations of tar is ‘--create’ (‘-c’), which you use to create a tar archive. We will explain ‘--create’ first because, in order to learn about the other operations, you will find it useful to have an archive available to practice on.

To make this easier, in this section you will first create a directory containing three files. Then, we will show you how to create an archive (inside the new directory). Both the directory, and the archive are specifically for you to practice on. The rest of this chapter and the next chapter will show many examples using this directory and the files you will create: some of those files may be other directories and other archives.

The three files you will archive in this example are called ‘blues’, ‘folk’, and ‘jazz’. The archive is called ‘collection.tar’.

This section will proceed slowly, detailing how to use ‘--create’ in verbose mode, and showing examples using both short and long forms. In the rest of the tutorial, and in the examples in the next chapter, we will proceed at a slightly quicker pace. This section moves more slowly to allow beginning users to understand how tar works.

2.6.1 Preparing a Practice Directory for Examples

To follow along with this and future examples, create a new directory called ‘practice’ containing files called ‘blues’, ‘folk’ and ‘jazz’. The files can contain any information you like: ideally, they should contain information which relates to their names, and be of different lengths. Our examples assume that ‘practice’ is a subdirectory of your home directory.

Now cd to the directory named ‘practice’; ‘practice’ is now your working directory. (Please note: Although the full file name of this directory is ‘/homedir/practice’, in our examples we will refer to this directory as ‘practice’; the homedir is presumed.)

In general, you should check that the files to be archived exist where you think they do (in the working directory) by running ls. Because you just created the directory and the files and have changed to that directory, you probably don’t need to do that this time.

It is very important to make sure there isn’t already a file in the working directory with the archive name you intend to use (in this case, ‘collection.tar’), or that you don’t care about its contents. Whenever you use ‘create’, tar will erase the current contents of the file named by ‘--file=archive-name’ (‘-f archive-name’) if it exists. tar will not tell you if you are about to overwrite an archive unless you specify an option which does this (see section Backup options, for the information on how to do so). To add files to an existing archive, you need to use a different option, such as ‘--append’ (‘-r’); see How to Add Files to Existing Archives: ‘--append’ for information on how to do this.

2.6.2 Creating the Archive

To place the files ‘blues’, ‘folk’, and ‘jazz’ into an archive named ‘collection.tar’, use the following command:

$ tar --create --file=collection.tar blues folk jazz

The order of the arguments is not very important, when using long option forms, however you should always remember to use option as the first argument to tar. For example, the following is wrong:

$ tar blues -c folk -f collection.tar jazz
tar: -c: Invalid blocking factor
Try 'tar --help' or 'tar --usage' for more information.

The error message is produced because tar always treats its first argument as an option (or cluster of options), even if it does not start with dash. This is traditional or old option style, called so because all implementations of tar have used it since the very inception of the tar archiver in 1970s. This option style will be explained later (see section Old Option Style), for now just remember to always place option as the first argument.

That being said, you could issue the following command:

$ tar --create folk blues --file=collection.tar jazz

However, you can see that this order is harder to understand; this is why we will list the arguments in the order that makes the commands easiest to understand (and we encourage you to do the same when you use tar, to avoid errors).

Note that the sequence ‘--file=collection.tar’ is considered to be one argument. If you substituted any other string of characters for collection.tar, then that string would become the name of the archive file you create.

The order of the options becomes more important when you begin to use short forms. With short forms, if you type commands in the wrong order (even if you type them correctly in all other ways), you may end up with results you don’t expect. For this reason, it is a good idea to get into the habit of typing options in the order that makes inherent sense. See section Short Forms with ‘create’, for more information on this.

In this example, you type the command as shown above: ‘--create’ is the operation which creates the new archive (‘collection.tar’), and ‘--file’ is the option which lets you give it the name you chose. The files, ‘blues’, ‘folk’, and ‘jazz’, are now members of the archive, ‘collection.tar’ (they are file name arguments to the ‘--create’ operation. See section Choosing Files and Names for tar, for the detailed discussion on these.) Now that they are in the archive, they are called archive members, not files. (see section members).

When you create an archive, you must specify which files you want placed in the archive. If you do not specify any archive members, GNU tar will complain.

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:

blues   folk   jazz   collection.tar

Creating the archive ‘collection.tar’ did not destroy the copies of the files in the directory.

Keep in mind that if you don’t indicate an operation, tar will not run and will prompt you for one. If you don’t name any files, tar will complain. You must have write access to the working directory, or else you will not be able to create an archive in that directory.

Caution: Do not attempt to use ‘--create’ (‘-c’) to add files to an existing archive; it will delete the archive and write a new one. Use ‘--append’ (‘-r’) instead. See section How to Add Files to Existing Archives: ‘--append’.

2.6.3 Running ‘--create’ with ‘--verbose’

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 create example above would appear as:

$ tar --create --verbose --file=collection.tar blues folk jazz
blues
folk
jazz

This example is just like the example we showed which did not use ‘--verbose’, except that tar generated three output lines.

In the rest of the examples in this chapter, we will frequently use verbose mode so we can show actions or tar responses that you would otherwise not see, and which are important for you to understand.

2.6.4 Short Forms with ‘create’

As we said before, the ‘--create’ (‘-c’) operation is one of the most basic uses of tar, and you will use it countless times. Eventually, you will probably want to use abbreviated (or “short”) forms of options. A full discussion of the three different forms that options can take appears in The Three Option Styles; for now, here is what the previous example (including the ‘--verbose’ (‘-v’) option) looks like using short option forms:

$ tar -cvf collection.tar blues folk jazz
blues
folk
jazz

As you can see, the system responds the same no matter whether you use long or short option forms.

One difference between using short and long option forms is that, although the exact placement of arguments following options is no more specific when using short forms, it is easier to become confused and make a mistake when using short forms. For example, suppose you attempted the above example in the following way:

$ tar -cfv collection.tar blues folk jazz

In this case, tar will make an archive file called ‘v’, containing the files ‘blues’, ‘folk’, and ‘jazz’, because the ‘v’ is the closest “file name” to the ‘-f’ option, and is thus taken to be the chosen archive file name. tar will try to add a file called ‘collection.tar’ to the ‘v’ archive file; if the file ‘collection.tar’ did not already exist, tar will report an error indicating that this file does not exist. If the file ‘collection.tar’ does already exist (e.g., from a previous command you may have run), then tar will add this file to the archive. Because the ‘-v’ option did not get registered, tar will not run under ‘verbose’ mode, and will not report its progress.

The end result is that you may be quite confused about what happened, and possibly overwrite a file. To illustrate this further, we will show you how an example we showed previously would look using short forms.

This example,

$ tar --create folk blues --file=collection.tar jazz

is confusing as it is. It becomes even more so when using short forms:

$ tar -c folk blues -f collection.tar jazz

It would be very easy to put the wrong string of characters immediately following the ‘-f’, but doing that could sacrifice valuable data.

For this reason, we recommend that you pay very careful attention to the order of options and placement of file and archive names, especially when using short option forms. Not having the option name written out mnemonically can affect how well you remember which option does what, and therefore where different names have to be placed.

2.6.5 Archiving Directories

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 followed the previous instructions in this tutorial, you should type:

$ cd ..
$

This will put you into the directory which contains ‘practice’, i.e., your home directory. Once in the superior directory, you can specify the subdirectory, ‘practice’, as a file name argument. To store ‘practice’ in the new archive file ‘music.tar’, type:

$ tar --create --verbose --file=music.tar practice

tar should output:

practice/
practice/blues
practice/folk
practice/jazz
practice/collection.tar

Note that the archive thus created is not in the subdirectory ‘practice’, but rather in the current 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. For example, you will probably not be able to store your home directory in an archive by invoking tar from the root directory; See section Absolute File Names. (Note also that ‘collection.tar’, 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.tar’ is extracted, the archive file ‘collection.tar’ will be re-written into the file system).

If you give tar a command such as

$ tar --create --file=foo.tar .

tar will report ‘tar: ./foo.tar is the archive; not dumped’. This happens because tar creates the archive ‘foo.tar’ in the current directory 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 ‘foo.tar’, and skips it. (It makes no sense to put an archive into itself.) GNU tar will continue in this case, and create the archive normally, except for the exclusion of that one file. (Please note: Other implementations of tar may not be so clever; they will enter an infinite loop when this happens, so you should not depend on this behavior unless you are certain you are running GNU tar. In general, it is wise to always place the archive outside of the directory being dumped.)

This document was generated on August 23, 2023 using texi2html 5.0.