6.10 Crossing File System Boundaries

tar will normally automatically cross file system boundaries in order to archive files which are part of a directory tree. You can change this behavior by running tar and specifying ‘--one-file-system’. This option only affects files that are archived because they are in a directory that is being archived; tar will still archive files explicitly named on the command line or through ‘--files-from’, regardless of where they reside.

‘--one-file-system’

Prevents tar from crossing file system boundaries when archiving. Use in conjunction with any write operation.

The ‘--one-file-system’ option causes tar to modify its normal behavior in archiving the contents of directories. If a file in a directory is not on the same file system as the directory itself, then tar will not archive that file. If the file is a directory itself, tar will not archive anything beneath it; in other words, tar will not cross mount points.

This option is useful for making full or incremental archival backups of a file system. If this option is used in conjunction with ‘--verbose’ (‘-v’), files that are excluded are mentioned by name on the standard error.

6.10.1 Changing the Working Directory

To change the working directory in the middle of a list of file names, either on the command line or in a file specified using ‘--files-from’ (‘-T’), use ‘--directory’ (‘-C’). This will change the working directory to the specified directory after that point in the list.

‘--directory=directory’

‘-C directory’

Changes the working directory in the middle of a command line.

For example,

$ tar -c -f jams.tar grape prune -C food cherry

will place the files ‘grape’ and ‘prune’ from the current directory into the archive ‘jams.tar’, followed by the file ‘cherry’ from the directory ‘food’. This option is especially useful when you have several widely separated files that you want to store in the same archive.

Note that the file ‘cherry’ is recorded in the archive under the precise name ‘cherry’, not ‘food/cherry’. Thus, the archive will contain three files that all appear to have come from the same directory; if the archive is extracted with plain ‘tar --extract’, all three files will be written in the current directory.

Contrast this with the command,

$ tar -c -f jams.tar grape prune -C food red/cherry

which records the third file in the archive under the name ‘red/cherry’ so that, if the archive is extracted using ‘tar --extract’, the third file will be written in a subdirectory named ‘red’.

You can use the ‘--directory’ option to make the archive independent of the original name of the directory holding the files. The following command places the files ‘/etc/passwd’, ‘/etc/hosts’, and ‘/lib/libc.a’ into the archive ‘foo.tar’:

$ tar -c -f foo.tar -C /etc passwd hosts -C /lib libc.a

However, the names of the archive members will be exactly what they were on the command line: ‘passwd’, ‘hosts’, and ‘libc.a’. They will not appear to be related by file name to the original directories where those files were located.

Note that ‘--directory’ options are interpreted consecutively. If ‘--directory’ specifies a relative file name, it is interpreted relative to the then current directory, which might not be the same as the original current working directory of tar, due to a previous ‘--directory’ option.

When using ‘--files-from’ (see section Reading Names from a File), you can put various tar options (including ‘-C’) in the file list. Notice, however, that in this case the option and its argument may not be separated by whitespace. If you use short option, its argument must either follow the option letter immediately, without any intervening whitespace, or occupy the next line. Otherwise, if you use long option, separate its argument by an equal sign.

For instance, the file list for the above example will be:

-C/etc
passwd
hosts
--directory=/lib
libc.a

To use it, you would invoke tar as follows:

$ tar -c -f foo.tar --files-from list

The interpretation of options in file lists is disabled by ‘--verbatim-files-from’ and ‘--null’ options.

6.10.2 Absolute File Names

By default, GNU tar drops a leading ‘/’ on input or output, and complains about file names containing a ‘..’ component. There is an option that turns off this behavior:

‘--absolute-names’

‘-P’

Do not strip leading slashes from file names, and permit file names containing a ‘..’ file name component.

When tar extracts archive members from an archive, it strips any leading slashes (‘/’) from the member name. This causes absolute member names in the archive to be treated as relative file names. This allows you to have such members extracted wherever you want, instead of being restricted to extracting the member in the exact directory named in the archive. For example, if the archive member has the name ‘/etc/passwd’, tar will extract it as if the name were really ‘etc/passwd’.

File names containing ‘..’ can cause problems when extracting, so tar normally warns you about such files when creating an archive, and rejects attempts to extracts such files.

Other tar programs do not do this. As a result, if you create an archive whose member names start with a slash, they will be difficult for other people with a non-GNU tar program to use. Therefore, GNU tar also strips leading slashes from member names when putting members into the archive. For example, if you ask tar to add the file ‘/bin/ls’ to an archive, it will do so, but the member name will be ‘bin/ls’(20).

Symbolic links containing ‘..’ or leading ‘/’ can also cause problems when extracting, so tar normally extracts them last; it may create empty files as placeholders during extraction.

If you use the ‘--absolute-names’ (‘-P’) option, tar will do none of these transformations.

To archive or extract files relative to the root directory, specify the ‘--absolute-names’ (‘-P’) option.

Normally, tar acts on files relative to the working directory—ignoring superior directory names when archiving, and ignoring leading slashes when extracting.

When you specify ‘--absolute-names’ (‘-P’), tar stores file names including all superior directory names, and preserves leading slashes. If you only invoked tar from the root directory you would never need the ‘--absolute-names’ option, but using this option may be more convenient than switching to root.

‘--absolute-names’

Preserves full file names (including superior directory names) when archiving and extracting files.

tar prints out a message about removing the ‘/’ from file names. This message appears once per GNU tar invocation. It represents something which ought to be told; ignoring what it means can cause very serious surprises, later.

Some people, nevertheless, do not want to see this message. Wanting to play really dangerously, one may of course redirect tar standard error to the sink. For example, under sh:

$ tar -c -f archive.tar /home 2> /dev/null

Another solution, both nicer and simpler, would be to change to the ‘/’ directory first, and then avoid absolute notation. For example:

$ tar -c -f archive.tar -C / home

See section Integrity, for some of the security-related implications of using this option.

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