Ubuntu Manpage: manilist - report status of files in a source directory

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 <Raphael.Manfredi@pobox.com>