patcol(1)
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 <[email protected]>. ram PAT(1)
Opportunity
Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.
Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.
Free Software
Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.
Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.
Free Books
The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.
Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.
Education
Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.
Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.
