The arch Patch Set Format
*************************

An arch patch set is a directory containing a number of files and subdirectories.  Each is described below.

Files:

             orig-dirs-index
             mod-dirs-index
             orig-files-index
             mod-files-index

Format:

             <file><tab><tag>

Sorting:

             sort -k 2

These contain indexes for all files and directories added, removed, or modified between the two trees.

Files:

             original-only-dir-metadata
             modified-only-dir-metadata

Format:

             <metadata><tab><name>

Sorting:

             sort -t '<tab>' -k 2

The field <metadata> contains literal output from the program file-metadata given the options --permissions.  Some example output is:

             --permissions 777

That output is also suitable for use as options and option arguments to the program set-file-metadata.   Future releases arch might add additional flags (beside just permissions).

The list records the file permissions for all directories persent in only one of the two trees.

Directories:

             removed-files-archive
             new-files-archive

Each of these directories contains complete copies of all files that occur in only the original tree (removed-files-archive) or modified tree (new-files-archive).  Each saved file is archived at the same relative location it had in its source tree, with permissions (at least) preserved.

Directory:

             patches

This directory contains a tree whose directory structure is a subset of the directory structure of the modified tree.  It contains modification data for directories and files common to both trees.

For a file stored in the modified tree at the path new_name, the patches directory may contain:

             new_name.link-orig

                     The original file is a symbolic link.
                     `new_name.link-orig' is a text file containing the
                     target of that link plus a final newline.

                     This file is only present if link target has changed,
                     or if the link was replaced by a regular file.

             new_name.link-mod

                     The modified file is a symbolic link and this file
                     is a text file containing the target for the link plus
                     a final newline.

                     This file is only present if the link target has
                     changed, or if the link replaces a regular file.

             new_name.original

                     This is a complete copy of the file from the original
                     tree, preserving (at least) permissions.

                     This file is only present if the file was replaced by
                     a symbolic link, or if the file contents can not be
                     handled by `diff(1)'.

             new_name.modified

                     This is a complete copy of the file from the modified
                     tree, preserving (at least) permissions.

                     This file is only present if the file replaces a
                     symbolic link, or if the file contents can not be
                     handled by `diff(1)'.

             new_name.patch

                     This is a standard context diff between the original
                     file and modified file.  One popular version of diff
                     (`GNU diff') generates non-standard context diffs by
                     omitting one copy of lines of context that are
                     identical between the original and modified file, so
                     for now, `.patch' files may have the same bug.
                     Fortunately, the only popular version of `patch'
                     (``GNU patch'') is tolerant of receiving such input.

             new_name.meta-orig
             new_name.meta-mod

                     File metadata (currenly only permissions) changed
                     between the two versions of the file.  These files
                     contain output from the `file-metadata' program with
                     the flags `--symlink --permissions', suitable for
                     comparison to similar output, and for use as options
                     and option arguments to `set-file-metadata'.

                     These files are also included if a regular file has
                     replaced a symbolic link or vice versa.

             new_name/=dir-meta-orig
             new_name/=dir-meta-mod

                     Directory metadata (currenly only permissions) changed
                     between the two versions of the directory containing
                     these files.  These files contain output from the
                     `file-metadata' program with the flags `--symlink
                     --permissions', suitable for comparison to similar
                     output, and for use as options and option arguments to
                     `set-file-metadata'.

Note: If a regular file (or symbolic link) replaces a directory, or vice versa, this is recorded as a file (or link) removed (or added) in one tree and added (or removed) in the other.