manilist

MANILIST(1)                 General Commands Manual                MANILIST(1)



NAME
       manilist - report status of files in a source directory

SYNOPSIS
       manilist [ -abcdhnptV ] [ -i extension ] [ -f manifest ] [ -p format ]
       [ -s string ] [ -w which ] [ -x extension ] [ -C separator ] [ -I
       included ] [ -L colsize ] [ -X excluded ] [ files or directories ]

DESCRIPTION
       Manilist scans a source directory and produces a report on the status
       of each file: whether it is up-to-date or not with respect to
       patchlevel.h , if it is missing from MANIFEST.new, and some other
       useful information which may be dynamically configured. It can be use
       to maintain a MANIFEST.new file, produce a detailed listing and status
       of a group of directories, etc... The rich set of options concur to
       make manilist a perfect low-level tool.

       Under its simplest invocation form at the top level directory of a
       package, with no arguments, manilist will scan the MANIFEST.new and
       produce a report on the status of each file listed there. Each line
       starts with a single character flag which indicates the state of the
       file, followed by the name of the file.

       What happens in fact is more complex than that. Manilist scans the
       MANIFEST.new file and then loops over all the files listed there.
       Internally, manilist maintains an inclusion and an exclusion list, both
       specifying extensions for files. For instance, the inclusion list could
       be ('.c', '.h') and the exclusion ('.o', ',v') so that C sources are
       included and object or RCS files excluded. By default, all files but
       those excluded are used.  Some other selections may be applied at this
       stage, as will be explained later on. For those files which pass this
       selection process, a report is issued according to a report format,
       which by default is "A:%c %n".  The letter A (or anything before the
       initial ':' character is the file selection specification we've been
       talking about. The remaining is the formatting, a string which is
       printed as-is, modulo some escape sequences.  It so happens that %c is
       the character flag and %n is the name of the current file.

       Generally speaking, manilist should be regarded as a tool which emits
       configurable reports on a set of files, selectively picking them among
       a list or by directly scanning the directories to see what's out
       there...

       By specifying a set of directories or files as arguments on the command
       line, you restrict the scanning area, limiting to reports concerning
       those files or directories. If you do not specify any, manilist
       restricts its report to the current directory and its subdirectories,
       unless the -t option is given.

OPTIONS
       Manilist recognizes the following options:

       -a             Make a report for all the files, regardless of what is
                      specified by the included and excluded suffix lists.

       -b             Assume current directory is the base (root) of the
                      package tree. When this option is not specified,
                      manilist will look for a .package file to indicate the
                      root directory of the package (also called the top) and
                      complain if it does not find it.

       -c             Check files against those listed in MANIFEST.new (or
                      whatever file specified via the -f option) and report
                      discrepancies via the %c macro.

       -d             Dump included and excluded suffix lists on stderr,
                      extensions being space separated. A good way to know the
                      default lists is to run: manilist -f /dev/null -bd.

       -f manifest    Specify an alternate manifest file, the default being to
                      use MANIFEST.new.

       -h             Print the usage help message and exit.

       -i extensions  Add new extensions to the included suffix list. The
                      extensions argument must list the suffixes separated by
                      spaces, as in -i '.ph .pl' to add both .ph and .pl to
                      the existing suffixes. Note that the argument needs to
                      be quoted to protect spaces against shell
                      interpretation.

       -n             Do not use any manifest file. Rather scan the
                      directories and act as with all the files there were
                      already listed in a manifest.

       -p format      Set the new printing format, which has the form
                      selection:string, with selection being a list of single
                      letters specifying which files from the manifest are to
                      be used for reports, and string being a message to print
                      as report, with some macro substitutions. It is also
                      possible to have column formatting by specifying a '|'
                      inside the string to delimit the different columns you
                      wish to see. See also -C and -L for more formatting
                      parameters.

       -s string      Specify the string part of the printing format (see -p
                      for a general description of the format). Available
                      macros are listed further down the manual page.

       -t             Start from the top directory (the root directory of the
                      distribution) regardless of the current directory. There
                      must be a .package file to indicate what the top
                      directory is.

       -w selection   Specifiy the selection part of the printing format.
                      Available selections will be discussed later.

       -x extensions  Add new extensions to the excluded suffix list. The
                      extensions argument must list the suffixes separated by
                      spaces, as in -x '.s .p' to add both .s and .p to the
                      existing list. Note that the argument needs to be quoted
                      to protect spaces against shell interpretation.

       -C separator   Give the column separator, which is to be used in place
                      of the '|' character in the report format string. By
                      default, it is a single space.

       -I included    Specify a new list of suffixes to be included in the
                      reports. This overrides the original default list
                      (whereas -i is used to add suffixes to the list).
                      Suffixes must be space separated.

       -L colsize     When using column formatting (the '|' character being
                      used to denote columns), this option may be used to
                      specify the maximum column width, separating each width
                      by a single ','. Leaving a width unspecified does not
                      impose any limit on its width. For instance, if the
                      format string is %n|%d|%t, one could limit the middle
                      column (descriptions from MANIFEST.new) to 40 characters
                      and the name column (first one) to 15 characters,
                      leaving the last one with no imposed limits, by using -L
                      15,40,.

       -V             Print version number and exit.

       -X excluded    Specify a new list of suffixes to be excluded in the
                      reports. This overrides the original default list
                      (whereas -x is used to add suffixes to the list).
                      Suffixes must be space separated.

USING FORMATS
       The flexibility of manilist is brought by its use of a dynamic
       formatting string for providing its reports. It is possible to specify
       a format via the -p option or just parts of it: the text string via -s
       and the file selection with -w.

   File Selection
       The leading part of the formatting string tells manilist which files
       you wish to see in the final report. Available selectors are:

       A    All the files but the excluded ones (i.e. those files whose suffix
            is listed in the exclusion list). This is the default action.
       a    All the files included and/or excluded (shortcut for ix). Note
            that files which are neither included nor excluded will not appear
            in the report.
       d    Report only for directories.
       f    Report only for files.
       i    Only included files are listed.
       m    Only those files or directories found in the manifest are listed.
       n    Only those files or directories not found in the manifest are
            listed.
       x    Only excluded files are listed.

       When you specify more than one letter, the resulting report depends on
       the nature of the selection. For d, f, m and n, a logical union is
       performed. This means specifying fd or mn is the same as not specifying
       anything, but it's less efficient since manilist is forced to perform
       the checks it would otherwise bypass. The i and x selectors are
       special: by default, all the files not excluded are reported.
       Specifying x also asks for excluded files. Specifying i restricts the
       report to the included files. Using both at the same time (ix) will
       force a report for files which are included or excluded.

   Macro Substitution
       The string part of the report format can make use of the following
       macros:

       %c   A character coding the status of the file.
       %d   Description from the manifest file, if any.
       %n   Name of the file (its path from the top directory).
       %s   Size of the file, in bytes.
       %t   Time stamp of the last modification.

   File Status
       The %c macro, giving a single character coding the file status, can
       expand into one of the following.
       .    The file is up to date (not newer than patchlevel.h).
       -    The file is present in the manifest but is missing.
       >    The file has been modified since last patch (newer than
            patchlevel.h).
       +    The file exists but is not listed in the manifest.
       o    The file exists but is not listed in the manifest and is older
            than patchlevel.h
       x    The file is listed in the manifest and exists, but has been
            excluded. Naturally, this will appear in the report only if the x
            selector is given in the report format.
       ?    The file is listed in the manifest, does not exist, and was
            excluded.

EXAMPLES
       The command

            manilist -ct -p 'ni:%n'

       will list all the source files from your distribution which are not
       listed in your MANIFEST.new file. Note that this includes only "source"
       files, that is to say files whose extension is listed in the inclusion
       list.  If you do not wish this restriction, replace the formatting
       string with n:%n (only the excluded files will not appear).

       To build an initial MANIFEST file, use:

            manilist -n -p 'Af:%n' > MANIFEST

       from the top directory. You will eventually want to fill in
       descriptions for each file listed in the manifest.

FILES
       MANIFEST.new        Default manifest file, listing files and giving a
                           small description for each of them.

AUTHOR
       Raphael Manfredi <ram@hptnos02.grenoble.hp.com>

SEE ALSO
       manifake(1), makedist(1), pat(1).



                                      ram                          MANILIST(1)