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

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