Prcs allows you to create a sequence of project versions out of a sequence of releases of a source directory tree. You may want to do this, for example, if you are installing successive versions of some system imported from elsewhere and wish to be able to retrieve old versions, while still saving space by storing only the changes between successive versions. (See package and unpackage, if you want to move or copy an entire project from one repository to another.)
The process is simple. For concreteness, let us use the name P
as the project name. For the first imported version, we create P
and populate it with the first version of the imported source files. In
the directory that contains the imported files, use the commands
% prcs checkout P % prcs populate P # Edit P.prj # % prcs checkin P
The editing of P.prj might consist of setting the
Project-Description
and New-Version-Log
attributes, and
possibly adding
:no-keywords
options to some files.
When you receive a new release of P
, place it in a directory
structure and, at the top directory of that structure, use the commands
% prcs checkout P P.prj % prcs populate -d P # Edit P.prj # % prcs checkin P
With the -d option, the prcs populate
command will add any
new files found in the working directory, but not listed in
P.prj, and will remove any files listed in P.prj, but not
present in the working directory.
Again, you will probably want to edit the New-Version-Log
attribute.
Imported software sources often have their own version designations, and
you may want to have the prcs major version identifiers include
all or part of these designations. Suppose the first such imported release is
called 1.0-beta
. In the working directory containing this release,
you might type
% prcs checkout -r1.0-beta.0 P % prcs populate P # Edit P.prj # % prcs checkin P
On receiving a new release from outside, say 1.1-beta
, you would put
it under a working directory and, from that directory, issue
the commands
% prcs checkout -r1.0-beta. P P.prj % prcs populate -d P # Edit P.prj # % prcs checkin -r1.1-beta. P
Sometimes, you will have local modifications or enhancements to a piece
of imported software, and want to bring your local version up to date
with successive parallel releases of the imported software.
To do this,
use the procedure above for keeping the imported
releases. Put your own local releases in another major version, let's
say Local
.
To start with,
you'll use the initial imported release:
% prcs checkout -rV P P.prj # Edit the project # % prcs checkin -rLocal P.prj
Here, V is whatever prcs version number you have assigned to the
vendor's (the imported) version.
Continue making your local modifications in major revision Local
.
When a
new external release comes in, first make
sure the most recent version of your local version is checked in.
Then put the new imported version into a fresh directory structure,
populate a project file, and check it in as outlined above.
For concreteness,
let's say that your most recent local version is designated Local.5, and
the newly-checked-in imported version is designated Vendor.3.
In the working directory for Vendor.3 (which you have just checked in), issue the command
% prcs merge -rLocal.@ -n P
to see where the discrepancies are (or use prcs diff
), and use
% prcs merge -rLocal.@ P
to merge in the revisions since the last external release with the local changes since the last release. Edit the files to resolve conflicts, and edit P.prj as usual. Finally, check the result back in with
% prcs checkin -rLocal P
which will create version Local.6. Its parent versions are Local.5 and Vendor.3. Alternatively, you could check out the local version, Local.5, and merge against the vendor branch
% prcs merge -rVendor.@ P
and checkin as Local.6. The resulting parent versions are the same in either case, with the sense of all the merge operations reversed.
Sometimes, you will find it desirable to rename the files you import and re-arrange their directory structure in your local version. You probably only want to perform this restructuring on the Local branch of the project, not the Vendor branch. Initially, you will create your first local version like this:
% prcs checkout -rV P P.prj # Rename files # # Edit P.prj to change the names in the Files attribute so # as to correspond to your renaming. % prcs checkin -rLocal P.prj
Editing P.prj here consists simply in changing the file names, not the internal file identifiers. For example, if the file doc/mogrify.1 in branch V is to be called man/mogrify2.1 in the Local branch, you would rename the file:
% mkdir man % mv doc/mogrify.1 man/mogrify2.1
and then you would edit the line for doc/mogrify.1 in P.prj, which might read
(doc/mogrify.1 (P/0_foobar.1 1.1 644))
originally, into
(man/mogrify2.1 (P/0_foobar.1 1.1 644))
The internal file identifier, therefore, records the correspondence between doc/mogrify.1 in the V branch and man/mogrify2.1 in the Local branch. When either of these files is updated and checked in, its new internal file identifier will be in the same internal-file family; thus the correspondence between the files is not lost.
The concept of an internal-file family (see Files attribute) was
introduced to allow prcs diff
and prcs merge
to “do
the right things” (that is, compare or merge against the appropriate files)
even in the face of such restructuring. For example, when comparing a Local
version to a Vendor version, prcs diff
will compare doc/mogrify.1
from the Vendor version with man/mogrify.1 in the working files of your
Local version.