manilist - report status of files in a source directory
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
]
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.
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.
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.
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.
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.
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.
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.
- MANIFEST.new
- Default manifest file, listing files and giving a small description for
each of them.
Raphael Manfredi <Raphael.Manfredi@pobox.com>