NAME¶
pat - patch generator tools
SYNOPSIS¶
pat [
-ahmnV ] [
filelist ]
patcil [
-abfhnpqsV ] [
filelist ]
patdiff [
-ahnV ] [
filelist ]
patbase [
-ahV ] [
filelist ]
patlog [
-hnruV ]
patmake [
-hV ]
patsend [
-hiquV ] [
patchlist ] [
recipients ]
patnotify [
-hquV ] [
recipients ]
patpost [
-hrV ]
patchlist newsgroups
patftp [
-hV ] [
patchlist ]
patname [
-ahnmV ]
-v version [
filelist ]
patsnap [
-ahV ] [
-o snapshot ] [
filelist ]
patcol [
-achnmsCV ] [
-d directory ] [
-f
mani ] [
-S snap ] [
filelist ]
patclean [
-ahnmV ] [
filelist ]
patindex
DESCRIPTION¶
Pat and its associated programs generate patches for any package that has
been stored under RCS. These programs hide many of the details of RCS that get
in your way when constructing and maintaining a package. All you need to do to
create a new patch is to edit your files, run pat, and furnish some
descriptions to RCS and in the generated patch file. Details such as how to
initialize a new RCS file, what the comment string should be, how create a new
branch, how to deal with subdirectories, how to do diffs and how to organize
the patch file are handled automatically.
Before using any of the pat programs you must initialize your package by running
packinit in the top-level directory of your package. This produces a .package
file that all of the dist programs make use of.
In any of the programs that want a filelist, if you specify
-a instead,
all files in MANIFEST.new will be processed. In any of the programs that want
a patchlist, a null patchlist means the current patch. You may use hyphens,
commas and spaces to delimit patch numbers. If the right side of a hyphen is
the null string, the current patchlevel is assumed as the maximum value. All
the programs invoked with
-h will print a small usage message with the
meaning of each available options. The
-V option gives the current
version number.
Pat itself is a wrapper program that calls patcil, patdiff, and patmake. Usually
you can just invoke pat and ignore all the others. Pat will update the
MANIFEST file, if necessary (it will be an exact copy of the MANIFEST.new
file, provided that a MANIFEST already existed), eventually calling patcil on
it.
If you specify
-n instead of a filelist, pat will find all files that are
newer than patchlevel.h, put you into an editor to trim down the list, then
use that file list. If every file of the list is removed,
pat will be
aborted.
Patcil is used to do a ci -l on any listed files. (It is assumed that you
always want to keep your files checked out.) In addition to the
-a
switch, there is a
-b switch which does a quick checkin of a set of
files. Instead of calling rcs on each file, it calls rcs on the whole list of
files. This is useful for checking in a trunk revision. When you are checking
in a new trunk revision you might also want to use the
-s flag which
will strip out old RCS Log entries from the previous revision so that you can
start over fresh. You probably should also use a
-f which is passed
through to the ci to force unchanged files to be checked in. To check in a new
trunk revision, I say
patcil -s -f -a
Patcil will ask for the log entry instead of letting ci do it, and has a little
prompter built in that lets you manipulate the message in various ways. Type h
for a listing of what you can do. One of the nicest things is that you can pop
up into an editor, optionally with a diff listing of the changes since the
last patch, in case you've forgotten what you changed. If you type a CR as the
first thing, it includes the previous log message. Exit the prompter with a
CR.
There are two different ways to use patcil. You can either call patcil yourself,
or let pat call it for you. It doesn't matter how many times you call patcil
before running pat, since patdiff knows what the last patch base is to compare
with. Patcil can be called in any of your directories; the other programs must
be called in your top-level directory (or in bugs, when meaningful).
When you are creating a new file at a given patchlevel, you must patcil it with
the
-p option. Otherwise, it will simply be checked-in as a new trunk
revision. The name of the file will be added to the MANIFEST.new if it does
not already appear in it. If the name is found along with a description, that
description will be passed through to rcs to properly initialize the RCS file.
Patbase can be used to reset the patch base to the current version when
you've scrapped the previous patch sequence and are making a new distribution
kit. What it really does is an rcs -Nlastpat:REV, where REV is the current
revision. If patdiff blows up and you want to set the patch base back to some
previous version, you have to call rcs -Nlastpat:REV yourself.
Patdiff actually does the diffs that go into the patch, comparing
whatever version -Nlastpat points to with the most recently checked in
version. It then updates -Nlastpat to point to the current version. It leaves
the diff sitting in the bugs subdirectory for patmake to pick up. It can
either use rcsdiff, or a diff command of your choice specified when you run
packinit, in case your diff is better than rcsdiff.
Patlog is invoked by
patmake usually, to update the
ChangeLog file (or whatever name that file has been given when you ran
packinit). It will gather log messages and launch an editor for you to
make the necessary updates. If you have configured your package to also
include RCS logs in the
ChangeLog, another editor session will be
launched for those too. Finally, a final log is built as a candidate entry for
ChangeLog, which you may also modify as you wish.
When you don't have configured a
ChangeLog file,
patlog will only
gather the information it needs to pass on to
patmake and will exit. If
you wish to call it yourself, you must do that after a least one sucessfull
patdiff run. I recommend using the
-n option the first time, and
then use the
-u option along with
-n on subsequent runs to
recreate files only when needed. The
-r option (which supersedes
-u) prevents
patlog from recreating an existing file, even if it
is out of date.
Patlog will call
patcil and
patdiff on your
ChangeLog file (after having stuffed the candidate log entry you edited
at the top of the file), unless prevented to do so by the
-n option.
This means the issued patch will update
ChangeLog with current patch
information, as you would expect it.
Patmake combines all the pieces of the patch into one file and invokes an
editor so you can add the subject and description. It throws all your log
messages in as Subjects and as Description, under the assumption that it's
easier to delete what you don't want than to remember everything you did.
You'll also want to expand each item in the Description so they don't just
repeat the Subject lines. If you have a
ChangeLog file, this must have
been done already, or your
ChangeLog will not accurately represent what
is described in the patch, given that it has already been updated when
patmake puts together all the pieces (see the note about
patlog
above).
Big patches will be split in order to keep size of each patch to a reasonable
size. This is handled automatically, so you don't have to bother with it. The
priority of each patch is merely intuited by
patmake, given the
assumption that small changes have a great priority.
Patsend, patpost and patftp are used to distribute your patches to the world.
Patsend mails a set of patches to a set of recipients. The
-u
switch adds all the currently registered users who have asked for patches to
be mailed to them, as well as the recipients specified while running
packinit. The
-i switch includes information with the patch
about how the user may deregister themselves so they do not receive future
patches automatically; this is also the default when the
-u switch is
used.
Patpost posts a set of patches to a set of newsgroups.
Patftp merely copies the patch into your public ftp directory.
Patnotify simply notifies users that a new patch has been released so
that they can retrieve it by themselves from an archive site or via e-mail if
they are interested. The
-u switch can be used to include all the
currently registered users who have asked for such a notification. The message
includes the patch priority and description, as well as instructions on how to
automatically request the patch (which will work only if you have
mailagent installed).
Both
patsend and
patnotify let you edit the address list before
actually sending anything, unless you add the
-q option.
Patname can be used to tag a set of files with a symbolic name (specified
with
-v). This will set the name for the most recent revision of each
file.
Patsnap will get a snapshot of your release by creating a SNAPSHOT file
(name can be changed via
-o) listing the file names and the latest RCS
revision number for that file. Such snapshots can be used to identify the
release at some random patchlevel and then later be able to retrieve it by
feeding the snapshot file to
patcol.
Patcol will check out a locked version of a file, eventually in an
alternate directory (specified with
-d, thus mirroring the distribution
tree). All the files which have no RCS counterpart (e.g. patchlevel.h) will be
simply copied by patcol. This is used by makedist to fake the distribution
before making the kits. By default, patcol will not do the copyright expansion
processing, but clients like
makedist force it by using its
-C
option. Alternatively, you may force copying of the checked-out version into a
directory by using the
-c switch in conjunction with
-d (or that
former switch is simply ignored).
Patcol can also take its file list from a SNAPSHOT file via the
-S
switch, in which case it will check out the files using the RCS version
specified by the snapshot file, such as one created by
patsnap. You may
instead specify
-a,
-m or
-n to respectively use all the
files in MANIFEST.new, all the modified files (the one which have been
patciled), or all the files newer than
patchlevel.h.
Patclean will remove the working files after having checked in all the
changes. You may restores your working files by using patcol.
Patindex may be used from the top level directory or within the
bugs directory. It will list all the patches and their
Subject:
lines. This program knows about compressed patches and will decompress them
while producing the listing.
RCS LAYER¶
This section describes the RCS layer, in case something in the tools breaks, so
that you may fix your RCS files and restart the operation.
All the patch tools get the main RCS trunk revision number out of your
.package files, say it's 2.5. Then, at the time you ran
packinit, you have chosen a branch for patches, usually number 1, which
means all your modifications will be stored on the 2.5.1 RCS branch. The tools
will create the branch for you when the time comes.
Each last released revision is tagged with an RCS
lastpat symbol. When
the patch is built by
patdiff, the lattest version on the 2.5.1 branch
is compared with the one tagged as
lastpat. This is why you may safely
issue more than one
patcil beffore issuing the patch and still have it
all worked out. Of course
patdiff will move the
lastpat tag to
the lattest branch revision after processing a given file.
All the log messages and the modified files are kept in your
bugs
directory, in hidden files (name starting with a dot). Those logs will be
collected when the patch is issued and the modified files are used by
pat's
-m switch.
Patdiff collects its patch hunks under the
bugs directory, in
files terminating with a
.nn extension, where
nn represents the
current patch level + 1. (Which is going to be the next patchlevel when the
patch will be made by
patmake, unless it is too big to fit in one
file).
Patlog prepares a set of files for
patmake: the
.clog file
collects the information that will go under the Description: section within
the patch, and
.xlog ones collect the
ChangeLog candidate entry.
Finally,
.rlog files store the RCS information that is to be included
in the
ChangeLog, if requested. Note that the topmost three lines are
garbage and are ignored by all the tools handling those files.
In order to start up a new baseline (i.e. to change the RCS trunk revision
number), you need to rerun
packinit and change that number. Then issue
a new
patcil, probably with the
-s,
-a and
-f
options...
FILES¶
- bugs/*.[0-9]+
- Diffs for each file, gathered by patmake to create a patch
- bugs/patch*
- Issued patches (can be compressed with compress only)
- bugs/.clog[0-9]+
- Description to be filled into the patch (or the first part if the patch is
split into several parts).
- bugs/.logs[0-9]+
- Log messages for that patch
- bugs/.mods[0-9]+
- Files modified in that patch (checked in with patcil)
- bugs/.pri[0-9]+
- The priority of the next patch, computed by patlog for
patmake's perusal.
- bugs/.rlog[0-9]+
- The RCS logs computed by patlog.
- bugs/.subj[0-9]+
- The Subject: lines for the next patch, computed by patlog for
patmake's perusal.
- bugs/.xlog[0-9]+
- The candidate entry for ChangeLog.
- users
- File filled in by mailagent's "@SH package" command,
normally issued by Configure, recording some of the users who kindly
registered themselves.
ENVIRONMENT¶
- PAGER
- Which pager to use in patcil (overrides default)
- EDITOR
- What editor should be used (overrides default)
- VISUAL
- Same role as EDITOR but this one is checked first
SEE ALSO¶
makedist(1),
metaconfig(1).
BUGS¶
Most of this should be built into RCS.
AUTHORS¶
Larry Wall (version 2.0).
Raphael Manfredi <ram@hptnos02.grenoble.hp.com>.