Unix/Linux Go Back    


NetBSD 6.1.5 - man page for rcsintro (netbsd section 1)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


RCSINTRO(1)									      RCSINTRO(1)

NAME
       rcsintro - introduction to RCS commands

DESCRIPTION
       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  com-
       mands: 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
       o      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.

       o      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.

       o      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.

       o      Maintain a tree of revisions.  RCS can maintain separate lines of  development  for
	      each  module.   It  stores a tree structure that represents the ancestral relation-
	      ships among revisions.

       o      Merge revisions and resolve conflicts.  Two separate lines of development of a mod-
	      ule  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.

       o      Control releases and configurations.  Revisions can be assigned symbolic names  and
	      marked  as  released, stable, experimental, etc.	With these facilities, configura-
	      tions of modules can be described simply and directly.

       o      Automatically identify each revision with name,  revision  number,  creation  time,
	      author,  etc.  The identification is like a stamp that can be embedded at an appro-
	      priate place in the text of a revision.  The  identification  makes  it  simple  to
	      determine which revisions of which modules make up a given configuration.

       o      Minimize	secondary  storage.  RCS needs little extra space for the revisions (only
	      the differences).  If intermediate revisions are deleted, the corresponding  deltas
	      are compressed accordingly.

   Getting Started with RCS
       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 synop-
       sis 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  f.c

       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  f.c

       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 locker.

       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 lock-
       ing 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 intelligently.)

       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 1.3.1.1 to
       the new revision.  For more information about branches, see rcsfile(5).

   Automatic Identification
       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 revi-
       sion 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
       Author: Walter F. Tichy.
       Manual Page Revision: ; Release Date: .
       Copyright (C) 1982, 1988, 1989 Walter F. Tichy.
       Copyright (C) 1990, 1991, 1992, 1993 Paul Eggert.

SEE ALSO
       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.

GNU										      RCSINTRO(1)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 05:21 PM.