Incremental archives keep information about contents of each dumped directory in special data blocks called dumpdirs.

Dumpdir is a sequence of entries of the following form:

     C FILENAME \0

where C is one of the control codes described below, FILENAME is the name of the file C operates upon, and \0 represents a nul character (ASCII 0).  The white space characters were added for readability, real dumpdirs do not contain them.

Each dumpdir ends with a single nul character.

The following table describes control codes and their meanings:

Y
     FILENAME is contained in the archive.

N
     FILENAME was present in the directory at the time the archive was made, yet it was not dumped to the archive, because it had not changed since the last backup.

D
     FILENAME is a directory.

R
     This code requests renaming of the FILENAME to the name specified with the following T command.

T
     Specify target file name for R command (see below).

X
     Specify temporary directory name for a rename operation (see below).

Codes Y, N and D require FILENAME argument to be a relative file name to the directory this dumpdir describes, whereas codes R, T and X require their argument to be an absolute file name.

The three codes R, T and X specify a renaming operation.  In the simplest case it is:

     Rsource\0Tdest\0

which means ``rename file source to file dest''.

However, there are cases that require using a temporary directory.  For example, consider the following scenario:

 1. Previous run dumped a directory foo which contained the following three directories:

          a
          b
          c

 2. They were renamed cyclically, so that:

          a became b
          b became c
          c became a

 3. New incremental dump was made.

This case cannot be handled by three successive renames, since renaming a to b will destroy existing directory. To handle such case a temporary directory is required. GNUTAR will create the following dumpdir (newlines have been added for readability):

     Xfoo\0
     Rfoo/a\0T\0
     Rfoo/b\0Tfoo/c\0
     Rfoo/c\0Tfoo/a\0
     R\0Tfoo/a\0

The first command, Xfoo\0, instructs the extractor to create a temporary directory in the directory foo.  Second command, Rfoo/aT\0, says ``rename file foo/a to the temporary directory that has just been created'' (empty file name after a command means use temporary directory).  Third and fourth commands work as usual, and, finally, the last command, R\0Tfoo/a\0 tells tar to rename the temporary directory to foo/a.

The exact placement of a dumpdir in the archive depends on the archive format (see Formats):

  * PAX archives

     In PAX archives, dumpdir is stored in the extended header of the corresponding directory, in variable GNU.dumpdir.

  * GNU and old GNU archives

     These formats implement special header type D, which is similar to ustar header 5 (directory), except that it precedes a data block containing the dumpdir.