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

  man pages->IRIX man pages -> rcsintro (1)              


RCSINTRO(1)							   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
     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 relationships among revisions.

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

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

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

									Page 1

RCSINTRO(1)							   RCSINTRO(1)

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

									Page 2

RCSINTRO(1)							   RCSINTRO(1)

     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 checkout
 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 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

									Page 3

RCSINTRO(1)							   RCSINTRO(1)

	  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

	  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


     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: 5.7; Release Date: 2000/10/27.
     Copyright c 1982, 1988, 1989 by Walter F. Tichy.

									Page 4

RCSINTRO(1)							   RCSINTRO(1)

     Copyright c 1990, 1991, 1992, 1993	by Paul	Eggert.

SEE ALSO    [Toc]    [Back]

     ci(1), co(1), ident(1), rcs(1), rcsdiff(1), rcsintro(1), rcsmerge(1),
     rlog(1), RCSsource(1)
     Walter F. Tichy, RCS--A System for	Version	Control, Software--Practice &
     Experience	15, 7 (July 1985), 637-654.

									PPPPaaaaggggeeee 5555
[ 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