*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->Tru64 Unix man pages -> rcsintro (1)              



NAME    [Toc]    [Back]

       rcsintro - introduction to RCS commands

DESCRIPTION    [Toc]    [Back]

       The  Revision  Control System (RCS) manages multiple revisions
 of files.  RCS  automates  the  storing,  retrieval,
       logging, identification, and merging of revisions.  RCS is
       useful for text that is revised  frequently,  for  example
       programs,  documentation,  graphics, papers, and form letters.

       The basic user interface is extremely simple.  The  novice
       only  needs  to  learn two commands: ci(1) and co(1).  ci,
       short for check in, deposits the contents of a  file  into
       an archival file called an RCS file.  An RCS file contains
       all revisions of a particular file.  co, short  for  check
       out, retrieves revisions from an RCS file.

   Functions of RCS    [Toc]    [Back]
       Store  and retrieve multiple revisions of text.  RCS saves
       all old revisions in a space  efficient  way.  Changes  no
       longer  destroy  the  original, because the previous revisions
  remain  accessible.   Revisions  can  be  retrieved
       according  to  ranges of revision numbers, symbolic names,
       dates, authors, and states.  Maintain a  complete  history
       of  changes.  RCS  logs all changes automatically. Besides
       the text of each revision, RCS stores the author, the date
       and  time  of  check-in, and a log message summarizing the
       change. The logging makes it easy to find  out  what  happened
  to a module, without having to compare source listings
 or having to track down colleagues.   Resolve  access
       conflicts.   When  two  or more programmers wish to modify
       the same revision, RCS alerts the programmers and prevents
       one  modification  from  corrupting the other.  Maintain a
       tree of revisions.  RCS can  maintain  separate  lines  of
       development  for  each module.  It stores a tree structure
       that represents the ancestral  relationships  among  revisions.
   Merge  revisions and resolve conflicts. Two separate
 lines of development of a module can be coalesced  by
       merging.  If  the  revisions  to be merged affect the same
       sections of code, RCS alerts the user about  the  overlapping
  changes.  Control releases and configurations. Revisions
  can  be  assigned  symbolic  names  and  marked  as
       released,  stable,  experimental,  etc. With these facilities,
 configurations of modules can  be  described  simply
       and  directly.   Automatically identify each revision with
       name, revision number, creation  time,  author,  etc.  The
       identification  is like a stamp that can be embedded at an
       appropriate place in the text of a revision. The identification
  makes  it  simple  to determine which revisions of
       which modules make up  a  given  configuration.   Minimize
       secondary  storage.   RCS needs little extra space for the
       revisions (only the differences).  If  intermediate  revisions
 are deleted, the corresponding deltas are compressed

   Getting Started with RCS    [Toc]    [Back]
       Suppose you have a file f.c that you  wish  to  put  under
       control  of  RCS. If you have not already done so, make an
       RCS directory with the command mkdir RCS

       Then invoke the check-in command ci f.c

       This command creates an RCS file  in  the  RCS  directory,
       stores  f.c  into  it as revision 1.1, and deletes f.c. It
       also asks you for a description.  The  description  should
       be  a  synopsis  of  the  contents of the file.  All later
       check-in commands will ask you  for  a  log  entry,  which
       should summarize the changes that you made.

       Files  in the RCS directory are called RCS files; the others
 are called working files. To get back the working file
       f.c  in the previous example, use the check-out command co

       This command extracts the latest  revision  from  the  RCS
       file  and writes it into f.c. If you want to edit f.c, you
       must lock it as you check it out with the  command  co  -l

       You can now edit f.c.

       Suppose  after  some editing you want to know what changes
       that you have made. The command rcsdiff f.c

       tells  you  the  difference  between  the  most   recently
       checked-in version and the working file. You can check the
       file back in by invoking ci f.c

       This increments the revision number properly.

       If ci complains with the message

       ci error: no lock set by your name

       then you have tried to check in a file even though you did
       not  lock it when you checked it out. Of course, it is too
       late now to do the check-out with locking, because another
       check-out  would  overwrite  your modifications.  Instead,
       invoke rcs -l f.c

       This command will lock the latest revision for you, unless
       somebody  else  got  ahead  of you already.  In this case,
       you'll have to negotiate with that person.

       Locking assures that you, and only you, can check  in  the
       next  update,  and avoids nasty problems if several people
       work on the same file. Even if a revision  is  locked,  it
       can still be checked out for reading, compiling, etc.  All
       that locking prevents is a check-in  by  anybody  but  the

       If  your  RCS  file  is private, i.e., if you are the only
       person who is going to deposit revisions into  it,  strict
       locking  is  not needed and you can turn it off. If strict
       locking is turned off, the owner of the RCS file need  not
       have  a  lock  for check-in; all others still do.  Turning
       strict locking off and on is done with the commands rcs -U
       f.c and rcs -L f.c

       If  you  don't want to clutter your working directory with
       RCS files, create a subdirectory called RCS in your  working
  directory,  and  move  all your RCS files there.  RCS
       commands will look  first  into  that  directory  to  find
       needed files.  All the commands discussed above will still
       work, without any modification. (Actually,  pairs  of  RCS
       and working files can be specified in three ways: (a) both
       are given, (b) only the working file is  given,  (c)  only
       the  RCS  file  is  given.  Both RCS and working files may
       have arbitrary path prefixes; RCS commands  pair  them  up

       To  avoid the deletion of the working file during check-in
       (in case you  want  to  continue  editing  or  compiling),
       invoke ci -l f.c or ci -u f.c

       These  commands  check  in  f.c  as  usual, but perform an
       implicit check-out.  The first form also locks the checked
       in  revision, the second one doesn't.  Thus, these options
       save you one check-out operation.  The first form is  useful
 if you want to continue editing, the second one if you
       just want to read the file. Both update the identification
       markers in your working file (see below).

       You  can give ci the number you want assigned to a checked
       in revision.  Assume all your revisions were numbered 1.1,
       1.2, 1.3, etc., and you would like to start release 2. The
       command ci -r2 f.c or ci -r2.1 f.c

       assigns the number 2.1 to the new revision. From then  on,
       ci  will  number  the  subsequent revisions with 2.2, 2.3,
       etc.  The corresponding co commands  co  -r2  f.c  and  co
       -r2.1 f.c

       retrieve the latest revision numbered 2.x and the revision
       2.1, respectively.  co without a revision  number  selects
       the  latest  revision on the trunk, i.e. the highest revision
 with a number consisting of two fields.  Numbers with
       more than two fields are needed for branches. For example,
       to start a branch at revision 1.3, invoke ci -r1.3.1 f.c

       This command starts a branch numbered 1 at  revision  1.3,
       and  assigns  the number to the new revision.  For
       more information about branches, see rcsfile(5).

   Automatic Identification    [Toc]    [Back]
       RCS can put special strings for identification  into  your
       source  and  object  code.  To obtain such identification,
       place the marker $Id$

       into your text, for instance inside a  comment.  RCS  will
       replace  this  marker with a string of the form $Id: filename
 revision date time author state  $

       With such a marker on the first page of each  module,  you
       can  always  see  with which revision you are working. RCS
       keeps the markers up to date automatically.  To  propagate
       the  markers  into  your object code, simply put them into
       literal character strings.  In C, this is done as follows:
       static char rcsid[] = "$Id$";

       The  command  ident  extracts  such markers from any file,
       even object code and dumps. Thus, ident lets you find  out
       which revisions of which modules were used in a given program.

       You may also find it useful to put the marker  $Log$  into
       your  text, inside a comment.  This marker accumulates the
       log messages that are requested during check-in. Thus, you
       can  maintain  the  complete history of your file directly
       inside it. There  are  several  additional  identification
       markers; see co(1) for details.

IDENTIFICATION    [Toc]    [Back]

       Author: Walter F. Tichy.
       Revision Number:; Release Date: 1993/10/07.
       Copyright (C) 1982, 1988, 1989 by Walter F. Tichy.
       Copyright (C) 1990, 1991 by Paul Eggert.

SEE ALSO    [Toc]    [Back]

       ci(1),  co(1),  ident(1), rcs(1), rcsdiff(1), rcsintro(1),
       rcsmerge(1), rlog(1)

       Walter F. Tichy, RCS--A System for Version Control,  Software--Practice
 & Experience 15, 7 (July 1985), 637-654.

[ Back ]
 Similar pages
Name OS Title
intro IRIX introduction to commands, application programs, and programming commands.
intro Tru64 Introduction to commands
cds_intro HP-UX Introduction to the CDS commands
dts_intro HP-UX Introduction to the DCE DTS commands
intro Linux Introduction to user commands
rpc_intro HP-UX Introduction to the DCE RPC programmer commands
kconfig HP-UX introduction to kernel configuration commands
intro Linux Introduction to administration and privileged commands
sec_intro HP-UX Introduction to the DCE Security administrative commands
introduction FreeBSD introduction to general commands (tools and utilities)
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service