You can find out more about, and get the latest version here: http://www.xcf.berkeley.edu/~jmacd/prcs.html
First, I created a directory called "hello" and put some files there:
phoenix% pwd /home/rkitover/hello phoenix% ls Makefile hello.c phoenix% cat Makefile default: hello hello: hello.o ld hello.o -o hello hello.o: hello.c gcc hello.c -o hello.o clean: rm -f core *.o hello phoenix% cat hello.c #include <stdio.h> int main () { printf("Hello, World!\n"); }Compiling it gives:
phoenix% make gcc hello.c -o hello.o ld hello.o -o hello phoenix% ls Makefile hello* hello.c hello.o*This comprises our "hello" project. Now we need to tell prcs to version it and put it in the repository:
phoenix% prcs checkout hello prcs: Created repository `/home/rkitover/PRCS', you may wish to run `prcs admin access' to set its permissions. prcs: Project not found in repository, initial checkout. prcs: You may now edit the file `hello.prj'.The repository is where prcs stores all of the project data. If you will be collaborating with others, you will want to keep the repository somewhere else, such as
/usr/local/prcs
to do this place the
command: PRCS_REPOSITORY=/usr/local/prcs export PRCS_REPOSITORYsomewhere in a global environment initialization file, such as
/etc/profile
and notify users about it. It is also safe to nfs
mount it across systems, with both read and read-write permissions.
For now we will keep our repository in the default place,
$HOME/PRCS
, which is created for us automatically. To allow others
to access your project, take a glance at prcs admin access --help
.
You can not run this command now because the project has not actually been
checked in yet, but we'll return to it later.
As an aside, you can always get good detailed information on any prcs command
by using prcs command --help
. The manual page man prcs
and the PRCS manual: http://www.xcf.berkeley.edu/~jmacd/prcs_doc.html.
PRCS told us this is the "initial checkout", meaning that there is no such project that it knows about currently, and it did not create one.
hello.prj
is the project file:
phoenix% cat hello.prj ;; -*- Prcs -*- (Created-By-Prcs-Version 1 2 14) (Project-Description "") (Project-Version hello 0 0) (Parent-Version -*- -*- -*-) (Version-Log "Empty project.") (New-Version-Log "") (Checkin-Time "Mon, 25 Oct 1999 16:18:23 -0700") (Checkin-Login rkitover) (Populate-Ignore ()) (Project-Keywords) (Files ;; This is a comment. Fill in files here. ;; For example: (prcs/checkout.cc ()) ) (Merge-Parents) (New-Merge-Parents)Notice that there are no files in this project yet. The command to add files to a project is
prcs populate [PROJECT [FILES]]
. Read about
it now with prcs populate --help
.
To populate our hello project:
phoenix% prcs populate prcs: 4 files were added. phoenix% cat hello.prj ;; -*- Prcs -*- (Created-By-Prcs-Version 1 2 14) (Project-Description "") (Project-Version hello 0 0) (Parent-Version -*- -*- -*-) (Version-Log "Empty project.") (New-Version-Log "") (Checkin-Time "Mon, 25 Oct 1999 16:18:23 -0700") (Checkin-Login rkitover) (Populate-Ignore ()) (Project-Keywords) (Files ;; This is a comment. Fill in files here. ;; For example: (prcs/checkout.cc ()) ;; Files added by populate at Mon, 25 Oct 1999 16:56:44 -0700, ;; to version 0.0(w), by rkitover: (hello () :no-keywords) (hello.o () :no-keywords) (hello.c ()) (Makefile ()) ) (Merge-Parents) (New-Merge-Parents)All this does is add files to the project file. It does not affect the PRCS repository in any way.
Now that our project is populated we can check it in:
phoenix% prcs checkin prcs: Created repository entry `hello'. prcs: Checking in project `hello' version 0.1.This actually created the project in the PRCS repository and gave it version "0.1".
Looking back at the project file, notice I made a mistake. We really do not
want unnecessary files like executables and object files versioned in our
project. To remove files from a project use the command prcs depopulate
[PROJECT [FILES]]
. Again see prcs depopulate --help
.
Commands like populate and depopulate do not modify the repository only
your local copy of the the project file, and they never delete any of your
working files (with the exception of merge).
So, to remove the files hello
and hello.o
:
phoenix% pwd /home/rkitover/hello phoenix% prcs depopulate hello hello.o hello prcs: Removed 2 files. phoenix% cat hello.prj ;; -*- Prcs -*- (Created-By-Prcs-Version 1 2 14) (Project-Description "") (Project-Version hello 0 1) (Parent-Version -*- -*- -*-) (Version-Log "") (New-Version-Log "") (Checkin-Time "Mon, 25 Oct 1999 17:12:35 -0700") (Checkin-Login rkitover) (Populate-Ignore ()) (Project-Keywords) (Files ;; This is a comment. Fill in files here. ;; For example: (prcs/checkout.cc ()) ;; Files added by populate at Mon, 25 Oct 1999 17:12:29 -0700, ;; to version 0.0(w), by rkitover: (hello.c (hello/2_hello.c 1.1 644)) (Makefile (hello/3_Makefile 1.1 644)) ;; Files deleted by depopulate at Mon, 25 Oct 1999 17:12:46 -0700, ;; from version 0.1(w), by rkitover: ; (hello () :no-keywords) ; (hello.o () :no-keywords) ) (Merge-Parents) (New-Merge-Parents) phoenix% prcs checkin prcs: Checking in project `hello' version 0.2.A checkin is necessary to update the repository. The reason
hello
is listed twice on the depopulate
command line
is because when using file lists with prcs commands the first argument is always
the project name, in this case "hello". Such commands must always be
performed in the top level directory of the project, where the .prj
file resides.
The minor version number (.2
in this case) is increased for
every checkin, the major version number never increases automatically.
To make sure files we do not want are ever included when we use
populate
to add files to project, let's specify a
populate-ignore
clause in the project file:
;; -*- Prcs -*- (Created-By-Prcs-Version 1 2 14) (Project-Description "") (Project-Version hello 0 2) (Parent-Version hello 0 1) (Version-Log "") (New-Version-Log "") (Checkin-Time "Mon, 25 Oct 1999 17:14:43 -0700") (Checkin-Login rkitover) (Populate-Ignore ( "\\.class$" "\\.so$" "\\.o$" "\\.log$" "\\.out$" "\\.state$" )) (Project-Keywords) (Files ;; This is a comment. Fill in files here. ;; For example: (prcs/checkout.cc ()) ;; Files added by populate at Mon, 25 Oct 1999 17:12:29 -0700, ;; to version 0.0(w), by rkitover: (hello.c (hello/2_hello.c 1.1 644)) (Makefile (hello/3_Makefile 1.1 644)) ;; Files deleted by depopulate at Mon, 25 Oct 1999 17:12:46 -0700, ;; from version 0.1(w), by rkitover: ; (hello () :no-keywords) ; (hello.o () :no-keywords) ) (Merge-Parents) (New-Merge-Parents)The lines above ignore C and java output files, as well as logs, etc. This way running
prcs populate
again on the project will not add files
that we don't want. The ignore patterns are regular expressions, use the above
form to ignore files with a certain suffix. For a general introduction to
regular expressions, see man ed
.
Now as for access permissions, to see the defaults:
phoenix% prcs admin access prcs: Setting access permissions for repository /home/rkitover/PRCS/. prcs: Repository entry owner: rkitover prcs: Repository entry group: rkitover prcs: Repository entry access: prcs: Owner: read/write prcs: Group: read only prcs: Other: read only(Press
ctrl+c
at the prompt). The prompts for this command
allow changing group ownership, group permissions and world permissions for the
project. "read only" means a person with the PRCS_REPOSITORY
environment variable pointed at the same repository can checkout and look at the
project, but not check it in. Someone with "read/write" permissions is able to
do both checkout and checkin versions. Don't worry about data getting lost with
PRCS, no one can step on someone else's toes toes irrevocably.
phoenix% prcs checkin -r PRODUCTION No previous major version named `PRODUCTION'. Create(nyq?)[y] y prcs: Checking in project `hello' version PRODUCTION.1.You can create as many branches as you like. Now you can go to any directory and
prcs checkout hello
to get the latest development
version, or prcs checkout -rPRODUCTION hello
to get the latest
production version. It is very easy to see differences and merge changes between
branches and minor versions.
"0"
of the "hello" project, and made a small change to "hello.c"
that removes the comma in the message: phoenix% prcs checkout -r0 hello prcs: Checkout project `hello' version 0.2. phoenix% ls Makefile hello.c hello.prj phoenix% cp hello.c goodbye.c phoenix% prcs populate hello goodbye.c prcs: One file was added. phoenix% echo "%s/Hello, World/Hello World/\nwq" | ex -s hello.c phoenix% prcs checkin prcs: Checking in project `hello' version 0.3.Then I made a couple of changes in PRODUCTION:
phoenix% prcs checkout -rPRODUCTION hello prcs: Checkout project `hello' version PRODUCTION.1. phoenix% ls Makefile hello.c hello.prj phoenix% echo "%s/Hello, World/hello world/\nwq" | ex -s hello.c phoenix% cat Makefile default: hello hello: hello.c gcc hello.c -o hello clean: rm -f core *.o hello phoenix% prcs checkin prcs: Checking in project `hello' version PRODUCTION.2.Now I want to merge the latest branch
"0"
changes into branch
"PRODUCTION": phoenix% prcs merge -r0 hello prcs: Working version: PRODUCTION.2(w) prcs: Common version: 0.2 prcs: Selected version: 0.3 prcs: *** Action on file `hello.c' prcs: Choose an action on file `hello.c' for rule 2: All three files exist and are different in each version. Please select(dnmrhvq!?)[m]I am merging against the latest minor version in branch
"0"
. My working version is the version I am working on, in
this case "PRODUCTION.2".
The common version is the version from which both of the versions
being merged are derived from, or the parent version. In this case it is
0.2
.
The selected version is the version against which the merge is being
peformed, in this case 0.3
is the latest version in branch
0
, which we specified with -r0
.
So by "all three files exist and are different..." it is telling us that both
the parent version, your version, and the version you are merging against have a
"hello.c"
that is different. And it gives us a prompt with a
reasonable default, with ? being help. Let's see what help says:
Please select(dnmrhvq!?)[m] ? prcs: Valid options are: prcs: d -- Delete working file. prcs: n -- Do nothing. prcs: m -- Merge selected and working file. prcs: r -- Replace working file with selected file. prcs: h -- Explain this condition. prcs: v -- View diffs. prcs: q -- Fail and abort PRCS. prcs: ! -- Take the default and do not offer this query again. Please select(dnmrhvq!?)[m]The only options that make sense in this situation are:
prcs: m -- Merge selected and working file. prcs: r -- Replace working file with selected file. prcs: v -- View diffs.You would use "m" to get a merged file, which very often requires editing by hand. To see what the differences are the option is "v":
Please select(dnmrhvq!?)[m] v Please select(swdlq?)[l] ? prcs: Valid options are: prcs: s -- View common -> selected diffs. prcs: w -- View common -> working diffs. prcs: d -- View selected -> working diffs. prcs: l -- [default] Leave this menu. prcs: q -- Fail and abort PRCS. Please select(swdlq?)[l] d prcs: Index: 0.3/hello.c 5c5 < printf("Hello World!\n"); --- > printf("hello world!\n"); Please select(swdlq?)[l] Please select(dnmrhvq!?)[m]"v" takes goes to a menu for the diff command, where we can get a diff between any two of the three versions. You almost always want the "d" option in the diff submenu, to see the differences between your version and the version you are merging against.
From here there are two options. If we decide that the person who made the changes in the version we are merging against did the right thing, then option "r" will replace our working file with a file from that version. Option "m" will merge the two files, in a nasty conflict like this one the result will look like this:
Please select(dnmrhvq!?)[m] m prcs: Merge file `hello.c' by rule 2, conflicts created ###### in another window... phoenix% cat hello.c #include <stdio.h> int main () { <<<<<<< PRODUCTION.2(w)/hello.c Tue, 26 Oct 1999 12:16:47 -0700 rkitover (hello/2_hello.c 1.1 644) printf("hello world!\n"); ======= printf("Hello World!\n"); >>>>>>> 0.3/hello.c Tue, 26 Oct 1999 11:43:02 -0700 rkitover (hello/2_hello.c 1.2 644) }By "conflicts created" PRCS is saying that the merge created conflicts that must be resolved manually. The first version of the conflicting line comes from
PRODUCTION.2
, and below under the ======
separator is the version of the line from 0.3
. You get the idea,
all you need to do now is delete the PRCS generated lines and pick the line you
wish to keep, or do something else appropriate for the case.
On with the merging process:
prcs: *** Action on file `goodbye.c' prcs: Choose an action on file `goodbye.c' for rule 14: Only the selected file is present. Please select(anhvq!?)[a] ? prcs: Valid options are: prcs: a -- Add selected file to working version. prcs: n -- Do nothing. prcs: h -- Explain this condition. prcs: v -- View diffs. prcs: q -- Fail and abort PRCS. prcs: ! -- Take the default and do not offer this query again. Please select(anhvq!?)[a]It's telling us that "Only the selected file is present", that this file only exists in the version against which we are merging. The default action, and the most reasonable here is "a", to add the file to our working version of the project. If however you are certain that you don't need this file, chose "n" to just continue with the merge process, and the file will not be added to either your project file or copied into your project directories. Here we chose a:
Please select(anhvq!?)[a] a prcs: Add file `goodbye.c' by rule 14 prcs: Merge against version 0.3 complete. phoenix% ls Makefile goodbye.c hello.c hello.log hello.prj obsolete/And the merge is completed!
You probably have some lingering doubts. What happened to the Makefile for
one? Let's see a diff of our working version PRODUCTION.2
and
0.3
:
phoenix% prcs diff -r0 hello -- -ruN Index: 0.3/hello.prj --- 0.3/hello.prj +++ PRODUCTION.2(w)/hello.prj @@ -1,13 +1,19 @@ ;; -*- Prcs -*- (Created-By-Prcs-Version 1 2 14) (Project-Description "") -(Project-Version hello 0 3) -(Parent-Version hello 0 2) +(Project-Version hello PRODUCTION 2) +(Parent-Version hello PRODUCTION 1) (Version-Log "") (New-Version-Log "") -(Checkin-Time "Tue, 26 Oct 1999 11:43:02 -0700") +(Checkin-Time "Tue, 26 Oct 1999 19:34:19 -0700") (Checkin-Login rkitover) -(Populate-Ignore ()) +(Populate-Ignore ( "\\.class$" + "\\.so$" + "\\.o$" + "\\.log$" + "\\.out$" + "\\.state$" +)) (Project-Keywords) (Files ;; This is a comment. Fill in files here. @@ -19,7 +25,7 @@ (hello.c (hello/2_hello.c 1.2 644)) - (Makefile (hello/3_Makefile 1.1 644)) + (Makefile (hello/3_Makefile 1.2 644)) ;; Files deleted by depopulate at Mon, 25 Oct 1999 17:12:46 -0700, ;; from version 0.1(w), by rkitover: @@ -27,10 +33,10 @@ ; (hello () :no-keywords) ; (hello.o () :no-keywords) -;; Files added by populate at Tue, 26 Oct 1999 11:37:25 -0700, -;; to version 0.2(w), by rkitover: - (goodbye.c (hello/4_goodbye.c 1.1 644)) -) + (goodbye.c (hello/4_goodbye.c 1.1 644))) (Merge-Parents) -(New-Merge-Parents) +(New-Merge-Parents + (0.3 complete + (hello.c hello.c hello.c m) (() () goodbye.c a)) +) Index: 0.3/hello.c --- 0.3/hello.c Tue, 26 Oct 1999 11:43:02 -0700 rkitover (hello/2_hello.c 1.2 644) +++ PRODUCTION.2(w)/hello.c Tue, 26 Oct 1999 19:37:39 -0700 rkitover (hello/2_hello.c 1.2 644) @@ -2,5 +2,9 @@ int main () { +<<<<<<< PRODUCTION.2(w)/hello.c Tue, 26 Oct 1999 19:13:38 -0700 rkitover (hello/2_hello.c 1.1.1.1 644) + printf("hello world!\n"); +======= printf("Hello World!\n"); +>>>>>>> 0.3/hello.c Tue, 26 Oct 1999 11:43:02 -0700 rkitover (hello/2_hello.c 1.2 644) } Index: 0.3/Makefile --- 0.3/Makefile Mon, 25 Oct 1999 17:12:35 -0700 rkitover (hello/3_Makefile 1.1 644) +++ PRODUCTION.2(w)/Makefile Tue, 26 Oct 1999 19:14:03 -0700 rkitover (hello/3_Makefile 1.2 644) @@ -1,10 +1,7 @@ default: hello -hello: hello.o - ld hello.o -o hello - -hello.o: hello.c - gcc hello.c -o hello.o +hello: hello.c + gcc hello.c -o hello clean: rm -f core *.o helloThe
prcs diff
command shows a diff of all the files between
projects, including the project file as you see above. I used the --
-ruN
option to produce a nice unified diff instead of the icky regular
diff, you will too.
So the project file and hello.c are obviously different, but so is Makefile.
What is happening is that in version 0.3
the Makefile was the same
as in 0.2
. This means to PRCS that 0.3
did not make
any changes to Makefile, only you did (in PRODUCTION.2
). Hence
there are no changes from 0.3
to that file for you to merge. For
now, assume merge will generally do what you want.
Keep in mind that prcs diff
will by default diff your working
version with the version you checked out, not the latest version in the
branch you are working on. To get a diff of your files with the latest version
use prcs diff -r0.@
.
So what is this new obsolete
directory?
phoenix% ls obsolete hello.c.v0 phoenix% cat obsolete/hello.c.v0 #include <stdio.h> int main () { printf("hello world!\n"); } phoenix% rm -rf obsoleteThis is the version of our file
hello.c
before the merge,
PRCS preserves it for us just in case, when manual conflict resolution is
required. So be careful and delete the obsolete directories when you don't need
them, and never populate them, or call any of your directories
obsolete
. You can add the pattern "obsolete/"
to your
populate-ignore clause in the project file to make sure.
And of course, never forget to check in your changes.
phoenix% ls Makefile goodbye.c hello.c hello.log hello.prj phoenix% prcs checkin prcs: Checking in project `hello' version PRODUCTION.3.
prcs merge
to make sure there
are no interim minor version releases made by other developers, if not merge
will tell you, otherwise it is necessary to merge the changes to preserve the
work done by the other developers, prcs diff -- -ruN
will be of
great help to see how versions differ. The merge process between minor versions
is the same as that between branches. Then don't forget to check in so that your
changes are preserved and available to others.
hello.c
to print its version (from the PRCS manual): phoenix% cat hello.c #include <stdio.h> /* $Format: "static char* version = \"$ProjectVersion: 0.1 $\";"$ */ static char* version = "x.x"; int main () { printf("Hello World!\n"); printf("From project hello version: %s\n", version); } phoenix% make gcc hello.c -o hello.o ld hello.o -o hello phoenix% ./hello Hello World! From project hello version: x.xOops! Keyword substitution in managed files only happens on checkin, and only affects the repository. In other words, you only get substitutions when you do a checkout. You don't want to do a checkout just to update a few lousy keywords, so there's the
prcs rekey
command. phoenix% prcs rekey prcs: Setting keys in project `hello' for version 0.3(w). phoenix% make gcc hello.c -o hello.o ld hello.o -o hello phoenix% ./hello Hello World! From project hello version: 0.3Don't forget to
e!
in vi if you are editing a file you
just rekeyed.
To add that nifty "Last modified on..." tag to html pages and not have to rely on SSI, something like this works very well:
<!-- $Format: "Last modified on: $Date$"$ --> Last modified on: Wed, 27 Oct 1999 14:39:46 -0700It doesn't matter what is under the format line, the whole line will be replaced when the project is re-keyed (explicitly or on checkout). So place something that makes sense for when the file has not been re-keyed.
You can also add comments to a checked in version, so that there is a history
of what all the checkins mean. There is a New-Version-Log
clause in
the project file where you can put comments, a Version-Log
clause
which is a copy of the New-Version-Log
from the version you are
working on, and a Project-Description
clause to describe what the
project is.
phoenix% grep Version-Log hello.prj (Version-Log "") (New-Version-Log "Just another checkin...") phoenix% grep Project-Description hello.prj (Project-Description "A PRCS Example") phoenix% prcs checkin prcs: Checking in project `hello' version PRODUCTION.4. phoenix% prcs info -l ... ... hello PRODUCTION.4 Wed, 27 Oct 1999 15:55:56 -0700 by rkitover Parent-Version: PRODUCTION.3 Version-Log: Just another checkin... Project-Description: A PRCS Example ... ...The command
prcs info -l
shows you the version history of the
whole project, including branches. It shows checkin time, parent version, the
checkin log message and the project description. It is good practice to describe
the versions you are checking in.
project-name.prj
file is. Then do: prcs checkin project-name relative/path/to/file1 ...The files will be checked in under a new minor version of the project, and will behave in all other respects like a full checkin.
On the other hand, if you messed up some file in the project and want to
retrieve a fresh copy from the latest minor version replacing your own, just do
prcs checkout project-name relative/path/to/file1 ...
to merge or
diff a set of files it is the same syntax. Remember to be in the top level
project directory, or bad things will happen.
That's all, have fun!