gnu/usr.bin/rcs/rcs/rcsintro.1

   1 .de Id
   2 .ds Rv \\$3
   3 .ds Dt \\$4
   4 ..
   5 .Id $FreeBSD: src/gnu/usr.bin/rcs/rcs/rcsintro.1,v 1.5 1999/08/27 23:36:53 peter Exp $
   6 .Id $DragonFly: src/gnu/usr.bin/rcs/rcs/rcsintro.1,v 1.2 2003/06/17 04:25:47 dillon Exp $
   7 .ds r \&\s-1RCS\s0
   8 .if n .ds - \%--
   9 .if t .ds - \(em
  10 .if !\n(.g \{\
  11 .       if !\w|\*(lq| \{\
  12 .               ds lq ``
  13 .               if \w'\(lq' .ds lq "\(lq
  14 .       \}
  15 .       if !\w|\*(rq| \{\
  16 .               ds rq ''
  17 .               if \w'\(rq' .ds rq "\(rq
  18 .       \}
  19 .\}
  20 .am SS
  21 .LP
  22 ..
  23 .TH RCSINTRO 1 \*(Dt GNU
  24 .SH NAME
  25 rcsintro \- introduction to RCS commands
  26 .SH DESCRIPTION
  27 The Revision Control System (\*r) manages multiple revisions of files.
  28 \*r automates the storing, retrieval, logging, identification, and merging
  29 of revisions.  \*r is useful for text that is revised frequently, for example
  30 programs, documentation, graphics, papers, and form letters.
  31 .PP
  32 The basic user interface is extremely simple.  The novice only needs
  33 to learn two commands:
  34 .BR ci (1)
  35 and
  36 .BR co (1).
  37 .BR ci ,
  38 short for \*(lqcheck in\*(rq, deposits the contents of a
  39 file into an archival file called an \*r file.  An \*r file
  40 contains all revisions of a particular file.
  41 .BR co ,
  42 short for \*(lqcheck out\*(rq, retrieves revisions from an \*r file.
  43 .SS "Functions of \*r"
  44 .IP \(bu
  45 Store and retrieve multiple revisions of text.  \*r saves all old
  46 revisions in a space efficient way.
  47 Changes no longer destroy the original, because the
  48 previous revisions remain accessible.  Revisions can be retrieved according to
  49 ranges of revision numbers, symbolic names, dates, authors, and
  50 states.
  51 .IP \(bu
  52 Maintain a complete history of changes.
  53 \*r logs all changes automatically.
  54 Besides the text of each revision, \*r stores the author, the date and time of
  55 check-in, and a log message summarizing the change.
  56 The logging makes it easy to find out
  57 what happened to a module, without having to compare
  58 source listings or having to track down colleagues.
  59 .IP \(bu
  60 Resolve access conflicts.  When two or more programmers wish to
  61 modify the same revision, \*r alerts the programmers and prevents one
  62 modification from corrupting the other.
  63 .IP \(bu
  64 Maintain a tree of revisions.  \*r can maintain separate lines of development
  65 for each module.  It stores a tree structure that represents the
  66 ancestral relationships among revisions.
  67 .IP \(bu
  68 Merge revisions and resolve conflicts.
  69 Two separate lines of development of a module can be coalesced by merging.
  70 If the revisions to be merged affect the same sections of code, \*r alerts the
  71 user about the overlapping changes.
  72 .IP \(bu
  73 Control releases and configurations.
  74 Revisions can be assigned symbolic names
  75 and marked as released, stable, experimental, etc.
  76 With these facilities, configurations of modules can be
  77 described simply and directly.
  78 .IP \(bu
  79 Automatically identify each revision with name, revision number,
  80 creation time, author, etc.
  81 The identification is like a stamp that can be embedded at an appropriate place
  82 in the text of a revision.
  83 The identification makes it simple to determine which
  84 revisions of which modules make up a given configuration.
  85 .IP \(bu
  86 Minimize secondary storage.  \*r needs little extra space for
  87 the revisions (only the differences).  If intermediate revisions are
  88 deleted, the corresponding deltas are compressed accordingly.
  89 .SS "Getting Started with \*r"
  90 Suppose you have a file
  91 .B f.c
  92 that you wish to put under control of \*r.
  93 If you have not already done so, make an \*r directory with the command
  94 .IP
  95 .B "mkdir  RCS"
  96 .LP
  97 Then invoke the check-in command
  98 .IP
  99 .B "ci  f.c"
 100 .LP
 101 This command creates an \*r file in the
 102 .B RCS
 103 directory,
 104 stores
 105 .B f.c
 106 into it as revision 1.1, and
 107 deletes
 108 .BR f.c .
 109 It also asks you for a description.  The description
 110 should be a synopsis of the contents of the file.  All later check-in
 111 commands will ask you for a log entry, which should summarize the
 112 changes that you made.
 113 .PP
 114 Files in the \*r directory are called \*r files;
 115 the others are called working files.
 116 To get back the working file
 117 .B f.c
 118 in the previous example, use the check-out
 119 command
 120 .IP
 121 .B "co  f.c"
 122 .LP
 123 This command extracts the latest revision from the \*r file
 124 and writes
 125 it into
 126 .BR f.c .
 127 If you want to edit
 128 .BR f.c ,
 129 you must lock it as you check it out with the command
 130 .IP
 131 .B "co  \-l  f.c"
 132 .LP
 133 You can now edit
 134 .BR f.c .
 135 .PP
 136 Suppose after some editing you want to know what changes that you have made.
 137 The command
 138 .IP
 139 .B "rcsdiff  f.c"
 140 .LP
 141 tells you the difference between the most recently checked-in version
 142 and the working file.
 143 You can check the file back in by invoking
 144 .IP
 145 .B "ci  f.c"
 146 .LP
 147 This increments the revision number properly.
 148 .PP
 149 If
 150 .B ci
 151 complains with the message
 152 .IP
 153 .BI "ci error: no lock set by " "your name"
 154 .LP
 155 then you have tried to check in a file even though you did not
 156 lock it when you checked it out.
 157 Of course, it is too late now to do the check-out with locking, because
 158 another check-out would
 159 overwrite your modifications.  Instead, invoke
 160 .IP
 161 .B "rcs  \-l  f.c"
 162 .LP
 163 This command will lock the latest revision for you, unless somebody
 164 else got ahead of you already.  In this case, you'll have to negotiate with
 165 that person.
 166 .PP
 167 Locking assures that you, and only you, can check in the next update, and
 168 avoids nasty problems if several people work on the same file.
 169 Even if a revision is locked, it can still be checked out for
 170 reading, compiling, etc.  All that locking
 171 prevents is a
 172 .I "check-in"
 173 by anybody but the locker.
 174 .PP
 175 If your \*r file is private, i.e., if you are the only person who is going
 176 to deposit revisions into it, strict locking is not needed and you
 177 can turn it off.
 178 If strict locking is turned off,
 179 the owner of the \*r file need not have a lock for check-in; all others
 180 still do.  Turning strict locking off and on is done with the commands
 181 .IP
 182 .BR "rcs  \-U  f.c" "     and     " "rcs  \-L  f.c"
 183 .LP
 184 If you don't want to clutter your working directory with \*r files, create
 185 a subdirectory called
 186 .B RCS
 187 in your working directory, and move all your \*r
 188 files there.  \*r commands will look first into that directory to find
 189 needed files.  All the commands discussed above will still work, without any
 190 modification.
 191 (Actually, pairs of \*r and working files can be specified in three ways:
 192 (a) both are given, (b) only the working file is given, (c) only the
 193 \*r file is given.  Both \*r and working files may have arbitrary path prefixes;
 194 \*r commands pair them up intelligently.)
 195 .PP
 196 To avoid the deletion of the working file during check-in (in case you want to
 197 continue editing or compiling), invoke
 198 .IP
 199 .BR "ci  \-l  f.c" "     or     " "ci  \-u  f.c"
 200 .LP
 201 These commands check in
 202 .B f.c
 203 as usual, but perform an implicit
 204 check-out.  The first form also locks the checked in revision, the second one
 205 doesn't.  Thus, these options save you one check-out operation.
 206 The first form is useful if you want to continue editing,
 207 the second one if you just want to read the file.
 208 Both update the identification markers in your working file (see below).
 209 .PP
 210 You can give
 211 .B ci
 212 the number you want assigned to a checked in
 213 revision.  Assume all your revisions were numbered 1.1, 1.2, 1.3, etc.,
 214 and you would like to start release 2.
 215 The command
 216 .IP
 217 .BR "ci  \-r2  f.c" "     or     " "ci  \-r2.1  f.c"
 218 .LP
 219 assigns the number 2.1 to the new revision.
 220 From then on,
 221 .B ci
 222 will number the subsequent revisions
 223 with 2.2, 2.3, etc.  The corresponding
 224 .B co
 225 commands
 226 .IP
 227 .BR "co  \-r2  f.c" "     and     " "co  \-r2.1  f.c"
 228 .PP
 229 retrieve the latest revision numbered
 230 .RI 2. x
 231 and the revision 2.1,
 232 respectively.
 233 .B co
 234 without a revision number selects
 235 the latest revision on the
 236 .IR trunk ,
 237 i.e. the highest
 238 revision with a number consisting of two fields.  Numbers with more than two
 239 fields are needed for branches.
 240 For example, to start a branch at revision 1.3, invoke
 241 .IP
 242 .B "ci  \-r1.3.1  f.c"
 243 .LP
 244 This command starts a branch numbered 1 at revision 1.3, and assigns
 245 the number 1.3.1.1 to the new revision.  For more information about
 246 branches, see
 247 .BR rcsfile (5).
 248 .SS "Automatic Identification"
 249 \*r can put special strings for identification into your source and object
 250 code.  To obtain such identification, place the marker
 251 .IP
 252 .B "$\&Id$"
 253 .LP
 254 into your text, for instance inside a comment.
 255 \*r will replace this marker with a string of the form
 256 .IP
 257 .BI $\&Id: "  filename  revision  date  time  author  state  " $
 258 .LP
 259 With such a marker on the first page of each module, you can
 260 always see with which revision you are working.
 261 \*r keeps the markers up to date automatically.
 262 To propagate the markers into your object code, simply put
 263 them into literal character strings.  In C, this is done as follows:
 264 .IP
 265 .ft 3
 266 static char rcsid[] = \&"$\&Id$\&";
 267 .ft
 268 .LP
 269 The command
 270 .B ident
 271 extracts such markers from any file, even object code
 272 and dumps.
 273 Thus,
 274 .B ident
 275 lets you find out
 276 which revisions of which modules were used in a given program.
 277 .PP
 278 You may also find it useful to put the marker
 279 .B $\&Log$
 280 into your text, inside a comment.  This marker accumulates
 281 the log messages that are requested during check-in.
 282 Thus, you can maintain the complete history of your file directly inside it.
 283 There are several additional identification markers; see
 284 .BR co (1)
 285 for
 286 details.
 287 .SH IDENTIFICATION
 288 Author: Walter F. Tichy.
 289 .br
 290 Manual Page Revision: \*(Rv; Release Date: \*(Dt.
 291 .br
 292 Copyright \(co 1982, 1988, 1989 Walter F. Tichy.
 293 .br
 294 Copyright \(co 1990, 1991, 1992, 1993 Paul Eggert.
 295 .SH "SEE ALSO"
 296 ci(1), co(1), ident(1), rcs(1), rcsdiff(1), rcsintro(1), rcsmerge(1), rlog(1)
 297 .br
 298 Walter F. Tichy,
 299 \*r\*-A System for Version Control,
 300 .I "Software\*-Practice & Experience"
 301 .BR 15 ,
 302 7 (July 1985), 637-654.
 303 .br