= [wiki:Notes]/RCSUsage =

== Quick notes on use of the repository ==

=== Basic Usage ===
 * use the {{{mirtree}}} tool to set up a workspace.
{{{
   unix% cd /data/DISK/somewhere
   unix% mkdir miriad_cabb
   unix% cd miriad_cabb
   unix% /nfs/atapplic/miriad/linux/bin/mirtree
}}}
 The last step creates a "miriad" subdirectory, and all the symlinks it sets up point to {{{/nfs/atapplic/miriad}}}.
 Don't worry about this - the next step will ensure you get the right version of code.
 * set the RCSINIT environment variable so it forces use of the CABB branch by default.
{{{
   unix% setenv RCSINIT "-rcabb"   # see ci(1) manpage for syntax
}}}
 * make your edits, and check in the changes
{{{
   unix% cd prog
   unix% co -l atlod.for
   unix% vi atlod.for
   unix% ci -u -m"support frobznagling mode" atlod.for
}}}
 * When you want to work with RCS files for a different project, you will need to unset RCSINIT
{{{
   unix% unsetenv RCSINIT
}}}

== Adding a new file ==
 To create a new file in the CABB branch it is first necessary to check in an
 empty file on the trunk as revision 1.0 (remove RCSINIT definition first):
{{{
   unix% unsetenv RCSINIT
   unix% mv mynewprog.for mynewprog.for.tmp
   unix% touch mynewprog.for
   unix% ci -r1.0 -m"Empty revision." mynewprog.for
}}}
 enter an appropriate description for the new file as ci requests.  Then create symbolic
 revision names:
{{{
   unix% rcs -ncabb_branchpoint:1.0 -ncabb:1.0.1 mynewprog.for
}}}
 Finally, create the initial revision on the branch:
{{{
   unix% mv mynewprog.for.tmp mynewprog.for
   unix% ci -u -rcabb.1 -m"Initial cabb branch checkin" mynewprog.for
}}}

== Merging changes ==
Now that we have a separate CABB branch, we need to make sure it doesn't get too far out of date with the main branch of miriad.
Periodically check for changes of checked out code (e.g. before checkin) and merge in changes from the main branch were possible.
{{{
   unix% ci -rcabb  atlod.for      % check in latest cabb version, before merge
   unix% co -rcabb -j1.6:1.8 atlod.for % merge changes between 1.6 and 1.8 on main branch into latest cabb version, output in atlod.for

   ignore this for now...
   unix% co -l -rcabb atlod.for    % check out the latest cabb branch version of atlod 
   unix% vi atlod.for              % make some cabb related changes
   unix% rlog atlod.for            % gives the revision history on both branches
   unix% rcsmerge -r1.8 atlod.for  % merges changes from 1.8 (assumed to be the most recent) into the checked out version
   unix% ci -rcabb atlod.for  -m"cabb changes, changes from 1.8 merged in" % make a note of the merge in the log message
}}}

== Background ==
 * The miriad master tree lives in {{{/nfs/atapplic/miriad}}}
 * There is a branch point on the "trunk", with the symbolic name "{{{cabb_branchpoint}}}"
 * The CABB tree branches off from there. The current latest version in the branch is denoted by the symbolic name "{{{cabb}}}".[[BR]]
   Example:
{{{
% rlog -h /nfs/atapplic/miriad/prog/atlod.for

RCS file: /nfs/atapplic/miriad/prog/RCS/atlod.for,v
Working file: /nfs/atapplic/miriad/prog/atlod.for
head: 1.6
branch:
locks: strict
access list:
symbolic names:
   cabb: 1.6.1
   cabb_branchpoint: 1.6
keyword substitution: kv
total revisions: 53; selected revisions: 53
description:
Convert an RPFITS file into Miriad uv format.

}}}
 * Make sure to use symbolic revision names, in general use.
 * You can use revision numbers in special cases (e.g. you are trying to reverse a checked-in change).[[BR]]
   But note that the correspondence of symbolic name and revision number is ''different'' for '''every''' RCS file.
 * The RCS revision numbers have four parts: L.U.B.S, being Level, Update, Branch, Sequence[[BR]]
   Without branches, you only get only L.U type numbers, e.g. 1.6.[[BR]]
   When you make a branch, the branch point is marked by the .B part of the number, e.g. 1.6.1. for the first branch off revision 1.6.[[BR]]
   When you change a file on a branch, the Sequence number is incremented, e.g. 1.6.1.1, 1.6.1.2, etc.
 * You may find {{{cvsgraph}}} useful to visualise the branch structure of a particular file
{{{
   unix% cvsgraph -r. RCS/atlod.for,v >atlod.png
}}}

=== See also ===
 * [wiki:Meetings/20080307]
 * [wiki:Notes/Subversion]
 * [http://books.google.com.au/books?id=PsH_GEjNrb0C Applying RCS and SCCS]

[wiki:Notes Notes Home]