Provided by: dist_3.5-30-3_all bug

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>.

                                               ram                                         PAT(1)