@need 3200

@node The arch Patch Set Format
@appendix The arch Patch Set Format

@geindex patch set format



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


@strong{Files:}

@example
@group
        orig-dirs-index
        mod-dirs-index
        orig-files-index
        mod-files-index
@end group
@group
@end group
@end example

@strong{Format:}

@example
@group
        <file><tab><tag>
@end group
@group
@end group
@end example

@strong{Sorting:}

@example
@group
        sort -k 2
@end group
@group
@end group
@end example

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


@strong{Files:}

@example
@group
        original-only-dir-metadata
        modified-only-dir-metadata
@end group
@group
@end group
@end example

@strong{Format:}

@example
@group
        <metadata><tab><name>
@end group
@group
@end group
@end example

@strong{Sorting:}

@example
@group
        sort -t '<tab>' -k 2
@end group
@group
@end group
@end example

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

@example
@group
        --permissions 777
@end group
@group
@end group
@end example

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


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


@strong{Directories:}

@example
@group
        removed-files-archive
        new-files-archive
@end group
@group
@end group
@end example

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


@strong{Directory:}

@example
@group
        patches
@end group
@group
@end group
@end example

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 @code{new_name}, the
@code{patches} directory may contain:

@example
@group
        new_name.link-orig
@end group
@group
@end group
@end example
@example
@group
                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.
@end group
@group
@end group
@end example
@example
@group
                This file is only present if link target has changed,
                or if the link was replaced by a regular file.
@end group
@group
@end group
@end example
@example
@group
        new_name.link-mod
@end group
@group
@end group
@end example
@example
@group
                The modified file is a symbolic link and this file
                is a text file containing the target for the link plus
                a final newline.
@end group
@group
@end group
@end example
@example
@group
                This file is only present if the link target has
                changed, or if the link replaces a regular file.
@end group
@group
@end group
@end example
@example
@group
        new_name.original
@end group
@group
@end group
@end example
@example
@group
                This is a complete copy of the file from the original
                tree, preserving (at least) permissions.
@end group
@group
@end group
@end example
@example
@group
                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)'.
@end group
@group
@end group
@end example
@example
@group
        new_name.modified
@end group
@group
@end group
@end example
@example
@group
                This is a complete copy of the file from the modified
                tree, preserving (at least) permissions.
@end group
@group
@end group
@end example
@example
@group
                This file is only present if the file replaces a
                symbolic link, or if the file contents can not be
                handled by `diff(1)'.
@end group
@group
@end group
@end example
@example
@group
        new_name.patch
@end group
@group
@end group
@end example
@example
@group
                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.
@end group
@group
@end group
@end example
@example
@group
        new_name.meta-orig
        new_name.meta-mod
@end group
@group
@end group
@end example
@example
@group
                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'.
@end group
@group
@end group
@end example
@example
@group
                These files are also included if a regular file has
                replaced a symbolic link or vice versa.
@end group
@group
@end group
@end example
@example
@group
        new_name/=dir-meta-orig
        new_name/=dir-meta-mod
@end group
@group
@end group
@end example
@example
@group
                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'.
@end group
@group
@end group
@end example

@strong{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.




