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 hello
The 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 obsolete
This 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: 1.86 $\";"$ */
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.x
Oops! 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: 2001/06/29 10:14:03 $"$ --> Last modified on: Tue, 09 Mar 2004 15:11:32 +0100It 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!