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)