File: prcs-tutorial.html

package info (click to toggle)
prcs 1.3.3-4
links: PTS
area: main
in suites: sarge
size: 4,128 kB
ctags: 3,354
sloc: cpp: 17,486; ansic: 8,132; sh: 4,710; perl: 2,729; lisp: 1,816; tcl: 1,142; lex: 354; makefile: 225; pascal: 85
file content (581 lines) | stat: -rw-r--r-- 26,541 bytes
parent folder | download | duplicates (3)
<html>
<head><title>PRCS Quick-start Guide</title></head>
<body>
<center>
	<h1>PRCS Quick-start Guide</h1>
	Version 0.1<br>
	Rafael Kitover (<a href="mailto:caelum@debian.org">caelum@debian.org</a>)
</center>


<h3>Introduction</h3>
PRCS stands for Project Revision Control System. The main difference between it and systems like RCS is that versioning happens on sets of files called projects as a whole, not on individual files. PRCS is also much simpler to use and requires considerably less administration than other systems systems such as CVS and Clearcase.<p>
You can find out more about, and get the latest version here: <a href="http://www.xcf.berkeley.edu/~jmacd/prcs.html">http://www.xcf.berkeley.edu/~jmacd/prcs.html</a>


<h3>Concepts</h3>
To begin working with PRCS you should understand the following concepts:
<ul>
<li><a href="#Projects">Projects</a>
<li><a href="#Versioning">Versioning and Branches</a>
<li><a href="#Merging">Merging</a>
<li><a href="#Cycle">Modify -&gt; Merge -&gt; Checkin Cycle</a>
<li><a href="#Keywords">Keywords</a>
<li><a href="#Partials">Partial Operations</a>
</ul>

<a name="Projects">
<h3>Projects</h3>
A project is a set of files and/or directories. To PRCS, projects are versioned units. Here we will make a simple project called "hello", shall we?<p>
First, I created a directory called "hello" and put some files there:
<pre>
phoenix% <b>pwd</b>
/home/rkitover/hello
phoenix% <b>ls</b>
Makefile  hello.c
phoenix% <b>cat Makefile</b>
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% <b>cat hello.c</b>
#include &lt;stdio.h&gt;

int main ()
{
        printf("Hello, World!\n");
}
</pre>
Compiling it gives:
<pre>
phoenix% <b>make</b>
gcc hello.c -o hello.o
ld hello.o -o hello
phoenix% <b>ls</b>
Makefile  hello*  hello.c  hello.o*
</pre>
This comprises our "hello" project. Now we need to tell prcs to version it and put it in the repository:
<pre>
phoenix% <b>prcs checkout hello</b>
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'.
</pre>
The <i>repository</i> 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 <code>/usr/local/prcs</code> to do this place the command:
<pre>
PRCS_REPOSITORY=/usr/local/prcs
export PRCS_REPOSITORY
</pre>
somewhere in a global environment initialization file, such as <code>/etc/profile</code> and notify users about it. It is also safe to nfs mount it across systems, with both read and read-write permissions.<p>
For now we will keep our repository in the default place, <code>$HOME/PRCS</code>, which is created for us automatically. To allow others to access your project, take a glance at <code>prcs admin access --help</code>. You can not run this command now because the project has not actually been <i>checked in</i> yet, but we'll return to it later.<p>
As an aside, you can always get good detailed information on any prcs command by using <code>prcs command --help</code>. The manual page <code>man prcs</code> and the PRCS manual: <a href="http://www.xcf.berkeley.edu/~jmacd/prcs_doc.html">http://www.xcf.berkeley.edu/~jmacd/prcs_doc.html</a>.<p>
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.<p>
<code>hello.prj</code> is the project file:
<pre>
phoenix% <b>cat hello.prj</b>
;; -*- 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)
</pre>
Notice that there are no files in this project yet. The command to add files to a project is <code>prcs populate [PROJECT [FILES]]</code>. Read about it now with <code>prcs populate --help</code>.<p>
To <i>populate</i> our hello project:
<pre>
phoenix% <b>prcs populate</b>
prcs: 4 files were added.
phoenix% <b>cat hello.prj</b>
;; -*- 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)
</pre>
All this does is add files to the project file. It does not affect the PRCS repository in any way.<p>
Now that our project is populated we can check it in:
<pre>
phoenix% <b>prcs checkin</b>
prcs: Created repository entry `hello'.
prcs: Checking in project `hello' version 0.1.
</pre>
This actually created the project in the PRCS repository and gave it version "0.1".<p>
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 <code>prcs depopulate [PROJECT [FILES]]</code>. Again see <code>prcs depopulate --help</code>. Commands like populate and depopulate <b>do not modify the repository</b> only your local copy of the the project file, and they never delete any of your working files (with the exception of merge).<p>
So, to remove the files <code>hello</code> and <code>hello.o</code>:
<pre>
phoenix% <b>pwd</b>
/home/rkitover/hello
phoenix% <b>prcs depopulate hello hello.o hello</b>
prcs: Removed 2 files.
phoenix% <b>cat hello.prj</b>
;; -*- 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% <b>prcs checkin</b>
prcs: Checking in project `hello' version 0.2.
</pre>
A checkin is necessary to update the repository. The reason <code>hello</code> is listed twice on the <code>depopulate</code> 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 <b>always</b> be performed in the top level directory of the project, where the <code>.prj</code> file resides.<p>
The minor version number (<code>.2</code> in this case) is increased for every checkin, the major version number never increases automatically.<p>
To make sure files we do not want are ever included when we use <code>populate</code> to add files to project, let's specify a <code>populate-ignore</code> clause in the project file:
<pre>
;; -*- 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)
<b>(Populate-Ignore (  "\\.class$"
                    "\\.so$"
                    "\\.o$"
                    "\\.log$"
                    "\\.out$"
                    "\\.state$"
))</b>
(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)
</pre>
The lines above ignore C and java output files, as well as logs, etc. This way running <code>prcs populate</code> 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 <code>man ed</code>.<p>
Now as for access permissions, to see the defaults:
<pre>
phoenix% <b>prcs admin access</b>
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
</pre>
(Press <code>ctrl+c</code> 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 <code>PRCS_REPOSITORY</code> 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.


<a name="Versioning">
<h3>Versioning and Branches</h3>


As you have seen, each checkin increments the minor version of a project. You can think of the major revision number as a "branch". For example, suppose we are ready to release our "hello" project into production, and keep the default "0" branch as the development branch:
<pre>
phoenix% <b>prcs checkin -r PRODUCTION</b>
No previous major version named `PRODUCTION'.  Create(nyq?)[y] <b>y</b>
prcs: Checking in project `hello' version PRODUCTION.1.
</pre>
You can create as many branches as you like. Now you can go to any directory and <code>prcs checkout hello</code> to get the latest development version, or <code>prcs checkout -rPRODUCTION hello</code> to get the latest production version. It is very easy to see differences and merge changes between branches and minor versions.


<a name="Merging">
<h3>Merging</h3>


Merging is the most difficult part of using PRCS. There is an in depth tutorial here: <a href="http://www.xcf.berkeley.edu/~jmacd/merge.html">http://www.xcf.berkeley.edu/~jmacd/merge.html</a>. Merging is the process of modifying your local copy of a project against one in the repository. Suppose, we added the file "goodbye.c" to branch <code>"0"</code> of the "hello" project, and made a small change to "hello.c" that removes the comma in the message:
<pre>
phoenix% <b>prcs checkout -r0 hello</b>
prcs: Checkout project `hello' version 0.2.
phoenix% <b>ls</b>
Makefile  hello.c  hello.prj
phoenix% <b>cp hello.c goodbye.c</b>
phoenix% <b>prcs populate hello goodbye.c</b>
prcs: One file was added.
phoenix% <b>echo "%s/Hello, World/Hello World/\nwq" | ex -s hello.c</b>
phoenix% <b>prcs checkin</b>
prcs: Checking in project `hello' version 0.3.
</pre>
Then I made a couple of changes in PRODUCTION:
<pre>
phoenix% <b>prcs checkout -rPRODUCTION hello</b>
prcs: Checkout project `hello' version PRODUCTION.1.
phoenix% <b>ls</b>
Makefile  hello.c  hello.prj
phoenix% <b>echo "%s/Hello, World/hello world/\nwq" | ex -s hello.c</b>
phoenix% <b>cat Makefile</b>
default: hello

hello: hello.c
        gcc hello.c -o hello

clean:
        rm -f core *.o hello
phoenix% <b>prcs checkin</b>
prcs: Checking in project `hello' version PRODUCTION.2.
</pre>
Now I want to merge the latest branch <code>"0"</code> changes into branch "PRODUCTION":
<pre>
phoenix% <b>prcs merge -r0 hello</b>
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] 
</pre>
I am merging <i>against</i> the latest minor version in branch <code>"0"</code>. My <i>working version</i> is the version I am working on, in this case "PRODUCTION.2".<p>
The <i>common version</i> is the version from which both of the versions being merged are derived from, or the parent version. In this case it is <code>0.2</code>.<p>
The <i>selected version</i> is the version against which the merge is being peformed, in this case <code>0.3</code> is the latest version in branch <code>0</code>, which we specified with <code>-r0</code>.<p>
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 <code>"hello.c"</code> that is different. And it gives us a prompt with a reasonable default, with ? being help. Let's see what help says:
<pre>
Please select(dnmrhvq!?)[m] <b>?</b>
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] 
</pre>
The only options that make sense in this situation are:
<pre>
prcs: m -- Merge selected and working file.
prcs: r -- Replace working file with selected file.
prcs: v -- View diffs.
</pre>
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":
<pre>
Please select(dnmrhvq!?)[m] <b>v</b>
Please select(swdlq?)[l] <b>?</b>
prcs: Valid options are:
prcs: s -- View common -&gt; selected diffs.
prcs: w -- View common -&gt; working diffs.
prcs: d -- View selected -&gt; working diffs.
prcs: l -- [default] Leave this menu.
prcs: q -- Fail and abort PRCS.
Please select(swdlq?)[l] <b>d</b>
prcs: Index: 0.3/hello.c
5c5
&lt;       printf("Hello World!\n");
---
&gt;       printf("hello world!\n");
Please select(swdlq?)[l] 
Please select(dnmrhvq!?)[m] 
</pre>
"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.<p>
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:
<pre>
Please select(dnmrhvq!?)[m] <b>m</b>
prcs: Merge file `hello.c' by rule 2, conflicts created

###### in another window...
phoenix% <b>cat hello.c</b>
#include &lt;stdio.h&gt;

int main ()
{
&lt;&lt;&lt;&lt;&lt;&lt;&lt; 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");
&gt;&gt;&gt;&gt;&gt;&gt;&gt; 0.3/hello.c Tue, 26 Oct 1999 11:43:02 -0700 rkitover (hello/2_hello.c 1.2 644)
}
</pre>
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 <code>PRODUCTION.2</code>, and below under the <code>======</code> separator is the version of the line from <code>0.3</code>. 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.<p>
On with the merging process:
<pre>
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] <b>?</b>
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] 
</pre>
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:
<pre>
Please select(anhvq!?)[a] <b>a</b>
prcs: Add file `goodbye.c' by rule 14
prcs: Merge against version 0.3 complete.
phoenix% <b>ls</b>
Makefile  goodbye.c  hello.c  hello.log  hello.prj  obsolete/
</pre>
And the merge is completed!<p>
You probably have some lingering doubts. What happened to the Makefile for one? Let's see a diff of our working version <code>PRODUCTION.2</code> and <code>0.3</code>:
<pre>
phoenix% <b>prcs diff -r0 hello -- -ruN</b>
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 ()
 {
+&lt;&lt;&lt;&lt;&lt;&lt;&lt; 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");
+&gt;&gt;&gt;&gt;&gt;&gt;&gt; 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
</pre>
The <code>prcs diff</code> command shows a diff of all the files between projects, including the project file as you see above. I used the <code>-- -ruN</code> option to produce a nice unified diff instead of the icky regular diff, you will too.<p>
So the project file and hello.c are obviously different, but so is Makefile. What is happening is that in version <code>0.3</code> the Makefile was the same as in <code>0.2</code>. This means to PRCS that <code>0.3</code> did not make any changes to Makefile, only you did (in <code>PRODUCTION.2</code>). Hence there are no changes from <code>0.3</code> to that file for you to merge. For now, assume merge will generally do what you want.<p>
Keep in mind that <code>prcs diff</code> will by default diff your working version with the version you checked out, <i>not</i> the latest version in the branch you are working on. To get a diff of your files with the latest version use <code>prcs diff -r0.@</code>.<p>
So what is this new <code>obsolete</code> directory?
<pre>
phoenix% <b>ls obsolete</b>
hello.c.v0
phoenix% <b>cat obsolete/hello.c.v0</b>
#include &lt;stdio.h&gt;

int main ()
{
        printf("hello world!\n");
}
phoenix% <b>rm -rf obsolete</b>
</pre>
This is the version of our file <code>hello.c</code> 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 <code>obsolete</code>. You can add the pattern <code>"obsolete/"</code> to your populate-ignore clause in the project file to make sure.<p>
And of course, never forget to check in your changes.<p>
<pre>
phoenix% <b>ls</b>
Makefile  goodbye.c  hello.c  hello.log  hello.prj
phoenix% <b>prcs checkin</b>
prcs: Checking in project `hello' version PRODUCTION.3.
</pre>


<a name="Cycle">
<h3>Modify -&gt; Merge -&gt; Checkin Cycle</h3>
The development cycle using PRCS when other developers are involved consists of checking out a project, making any necessary changes, then doing a <code>prcs merge</code> 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, <code>prcs diff -- -ruN</code> 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.


<a name="Keywords">
<h3>Keywords</h3>
You will often want to put in versioning information into your sources. Let's modify <code>hello.c</code> to print its version (from the <a href="http://www.xcf.berkeley.edu/~jmacd/prcs_doc.html#SEC47">PRCS manual</a>):
<pre>
phoenix% <b>cat hello.c</b>
#include &lt;stdio.h&gt;


<i>/* &#36;Format: "static char* version = \"$ProjectVersion: 0.1 $\";"&#36; */
static char* version = "x.x";

int main ()
{
        printf("Hello World!\n");
        <i>printf("From project hello version: %s\n", version);</i>
}
phoenix% <b>make</b>
gcc hello.c -o hello.o
ld hello.o -o hello
phoenix% <b>./hello</b>
Hello World!
From project hello version: x.x
</pre>
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 <code>prcs rekey</code> command.
<pre>
phoenix% <b>prcs rekey</b>
prcs: Setting keys in project `hello' for version 0.3(w).
phoenix% <b>make</b>
gcc hello.c -o hello.o
ld hello.o -o hello
phoenix% <b>./hello</b>
Hello World!
From project hello version: 0.3
</pre>
Don't forget to <b><code>e!</code></b> in vi if you are editing a file you just rekeyed.<p>
To add that nifty "Last modified on..." tag to html pages and not have to rely on SSI, something like this works very well:
<pre>
&lt;!-- $Format: "Last modified on: $Date: 2001/06/29 10:14:03 $"$ --&gt;
Last modified on: Wed, 27 Oct 1999 14:39:46 -0700
</pre>
It 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.<p>
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 <code>New-Version-Log</code> clause in the project file where you can put comments, a <code>Version-Log</code> clause which is a copy of the <code>New-Version-Log</code> from the version you are working on, and a <code>Project-Description</code> clause to describe what the project is.
<pre>
phoenix% <b>grep Version-Log hello.prj</b>
(Version-Log "")
(New-Version-Log "Just another checkin...")
phoenix% <b>grep Project-Description hello.prj</b>
(Project-Description "A PRCS Example")
phoenix% <b>prcs checkin</b>
prcs: Checking in project `hello' version PRODUCTION.4.
phoenix% <b>prcs info -l</b>
...
...
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
...
...
</pre>
The command <code>prcs info -l</code> 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.


<a name="Partials">
<h3>Partial Operations</h3>
Otherwise known as a "partial checkin". First, change to the directory where your <code>project-name.prj</code> file is. Then do:
<pre>
<b>prcs checkin project-name relative/path/to/file1 ...</b>
</pre>
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.<p>
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 <code>prcs checkout project-name relative/path/to/file1 ...</code> 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.<p>
<b>That's all, have fun!</b>

<p>
<hr>
<address>
<!-- $Format: "Last modified on: $Date: 2001/06/29 10:14:03 $"$ -->
Last modified on: Wed, 27 Oct 1999 14:39:46 -0700
<br>
	Copyright (C) 1999 Rafael Kitover (<a href="mailto:caelum@debian.org">caelum@debian.org</a>)<br>
	Terms: GPL v2+
</address>
</body>
</html>