NAME
     co - check out RCS revisions

SYNOPSIS
     co [ options ] file ...

DESCRIPTION
     Co retrieves a revision from each RCS  file  and  stores  it
     into  the corresponding working file.  Each file name ending
     in `,v' is taken to be an RCS  file;  all  other  files  are
     assumed  to  be  working  files.   If only a working file is
     given, co tries to find the corresponding RCS  file  in  the
     directory ./RCS and then in the current directory.  For more
     details, see the file naming section below.

     Revisions of an RCS  file  may  be  checked  out  locked  or
     unlocked. Locking a revision prevents overlapping updates. A
     revision checked out for reading or processing  (e.g.,  com-
     piling) need not be locked. A revision checked out for edit-
     ing and later checkin must normally be locked. Co with lock-
     ing  fails  if  the  revision to be checked out is currently
     locked by another user.  (A lock  may  be  broken  with  the
     rcs(L) command.) Co with locking also requires the caller to
     be on the access list of the RCS  file,  unless  he  is  the
     owner  of  the  file or the superuser, or the access list is
     empty.  Co without locking is not subject to accesslist res-
     trictions, and is not affected by the presence of locks.

     A revision is selected by options  for  revision  or  branch
     number,  checkin  date/time,  author,  or  state.   When the
     selection options are applied in combination,  co  retrieves
     the  latest revision that satisfies all of them.  If none of
     the selection options is specified, co retrieves the  latest
     revision  on the default branch (normally the trunk, see the
     -b option of rcs(L)).  A revision or branch  number  may  be
     attached  to  any  of the options -f, -l, -p, -q, -r, or -u.
     The options -d (date), -s (state), and -w (author)  retrieve
     from  a  single branch, the selected branch, which is either
     specified by one of -f,..., -u, or the default branch.

     A co command applied  to  an  RCS  file  with  no  revisions
     creates a zero-length working file.  Co always performs key-
     word substitution (see below).

     -r[rev]    retrieves the latest  revision  whose  number  is
                less  than  or  equal to rev.  If rev indicates a
                branch rather than a revision, the  latest  revi-
                sion  on  that  branch  is  retrieved.  If rev is
                omitted,  the  latest  revision  on  the  default
                branch   (see   the   -b  option  of  rcs(L))  is
                retrieved.   Rev  is  composed  of  one  or  more
                numeric  or symbolic fields separated by `.'. The
                numeric equivalent of a symbolic field is  speci-
                fied with the -n option of the commands ci(L) and
                rcs(L).

     -l[rev]    same  as  -r,  except  that  it  also  locks  the
                retrieved revision for the caller.  See option -r
                for handling of the revision number rev .

     -u[rev]    same as -r, except that it unlocks the  retrieved
                revision (if it was locked by the caller). If rev
                is omitted,  -u  retrieves  the  latest  revision
                locked  by the caller; if no such lock exists, it
                retrieves the  latest  revision  on  the  default
                branch.

     -f[rev]    forces the overwriting of the working file;  use-
                ful  in connection with -q.  See also the section
                on file modes below.

     -p[rev]    prints the retrieved  revision  on  the  standard
                output  rather  than  storing  it  in the working
                file.  This option is useful when co is part of a
                pipe.

     -q[rev]    quiet mode; diagnostics are not printed.

     -ddate     retrieves the latest  revision  on  the  selected
                branch  whose  checkin  date/time is less than or
                equal to date.  The date and time may be given in
                free  format  and  are  converted  to local time.
                Examples of formats for date:

                22-April-1982, 17:20-CDT,
                2:25 AM, Dec. 29, 1983,
                Tue-PDT, 1981, 4pm Jul 21         (free format),
                Fri, April 16 15:52:25 EST 1982 (output of ctime).

                Most  fields  in  the  date  and  time   may   be
                defaulted.   Co  determines  the  defaults in the
                order year, month, day, hour, minute, and  second
                (most  to  least  significant).  At  least one of
                these fields must be provided. For omitted fields
                that  are of higher significance than the highest
                provided field, the current values  are  assumed.
                For all other omitted fields, the lowest possible
                values are assumed.  For example, the  date  "20,
                10:30"  defaults  to  10:30:00 of the 20th of the
                current month and current  year.   The  date/time
                must be quoted if it contains spaces.

     -sstate    retrieves the latest  revision  on  the  selected
                branch whose state is set to state.

     -w[login]  retrieves the latest  revision  on  the  selected
                branch  which  was  checked  in  by the user with
                login name login. If the argument login is  omit-
                ted, the caller's login is assumed.

     -jjoinlist generates a new revision which is the join of the
                revisions  on  joinlist.   Joinlist  is  a comma-
                separated list of pairs of  the  form  rev2:rev3,
                where  rev2  and  rev3  are (symbolic or numeric)
                revision numbers.  For  the  initial  such  pair,
                rev1  denotes  the revision selected by the above
                options -r, ..., -w. For all  other  pairs,  rev1
                denotes  the  revision  generated by the previous
                pair. (Thus, the output of one join  becomes  the
                input to the next.)

                For each pair, co joins revisions rev1  and  rev3
                with  respect  to  rev2.   This  means  that  all
                changes that transform rev2 into rev1 are applied
                to  a  copy of rev3.  This is particularly useful
                if rev1 and rev3 are the  ends  of  two  branches
                that  have  rev2  as a common ancestor. If rev1 <
                rev2 < rev3 on the same branch, joining generates
                a  new  revision which is like rev3, but with all
                changes that lead from rev1 to rev2  undone.   If
                changes  from  rev2  to rev1 overlap with changes
                from rev2  to  rev3,  co  prints  a  warning  and
                includes  the  overlapping sections, delimited by
                the    lines    <<<<<<< rev1,    =======,     and
                >>>>>>> rev3.

                For the initial pair, rev2 may  be  omitted.  The
                default  is  the  common ancestor.  If any of the
                arguments indicate branches, the latest revisions
                on  those  branches  are assumed.  The options -l
                and -u lock or unlock rev1.

KEYWORD SUBSTITUTION
     Strings of the form $keyword$ and $keyword:...$ embedded  in
     the   text   are   replaced   with   strings   of  the  form
     $keyword: value $, where keyword and value are pairs  listed
     below.   Keywords may be embedded in literal strings or com-
     ments to identify a revision.

     Initially, the user enters strings of  the  form  $keyword$.
     On  checkout,  co replaces these strings with strings of the
     form $keyword: value $. If a revision containing strings  of
     the latter form is checked back in, the value fields will be
     replaced during the next checkout.  Thus, the keyword values
     are automatically updated on checkout.


     Keywords and their corresponding values:

     $Author$     The login name of the user who checked  in  the
                  revision.

     $Date$       The date and time the revision was checked in.

     $Header$     A standard header containing the full  pathname
                  of the RCS file, the revision number, the date,
                  the author,  the  state,  and  the  locker  (if
                  locked).

     $Id$         Same as $Header$, except that the RCS file name
                  is without a path.

     $Locker$     The login name of the user who locked the revi-
                  sion (empty if not locked).

     $Log$        The log message supplied during  checkin,  pre-
                  ceded by a header containing the RCS file name,
                  the revision number, the author, and the  date.
                  Existing   log   messages   are  NOT  replaced.
                  Instead, the new log message is inserted  after
                  $Log:...$.   This  is useful for accumulating a
                  complete change log in a source file.

     $RCSfile$    The name of the RCS file without path.

     $Revision$   The revision number assigned to the revision.

     $Source$     The full pathname of the RCS file.

     $State$      The state assigned to the revision with the  -s
                  option of rcs(L) or ci(L).

     Pairs of RCS files and working files may be specified  in  3
     ways (see also the example section).

     1) Both the RCS file and the working file are given. The RCS
     file  name  is  of the form path1/workfile,v and the working
     file name is of the form path2/workfile,  where  path1/  and
     path2/  are (possibly different or empty) paths and workfile
     is a file name.

     2) Only the RCS file is given.  Then  the  working  file  is
     created  in  the  current  directory and its name is derived
     from the name of the RCS file by  removing  path1/  and  the
     suffix ,v.

     3) Only the working file is given.  Then co looks for an RCS
     file  of  the  form path2/RCS/workfile,v or path2/workfile,v
     (in this order).
     If the RCS file is specified without a path in  1)  and  2),
     then  co looks for the RCS file first in the directory ./RCS
     and then in the current directory.

EXAMPLES
     Suppose the current directory contains a subdirectory  `RCS'
     with  an  RCS  file `io.c,v'. Then all of the following com-
     mands retrieve the latest  revision  from  `RCS/io.c,v'  and
     store it into `io.c'.

          co  io.c;    co  RCS/io.c,v;   co  io.c,v;
          co  io.c  RCS/io.c,v;    co  io.c  io.c,v;
          co  RCS/io.c,v  io.c;    co  io.c,v  io.c;

FILE MODES
     The working file inherits the read and  execute  permissions
     from  the  RCS file. In addition, the owner write permission
     is turned on, unless the file is checked  out  unlocked  and
     locking is set to strict (see rcs(L)).

     If a file with the name of the working file  exists  already
     and  has  write  permission, co aborts the checkout if -q is
     given, or asks whether to abort if -q is not given.  If  the
     existing  working  file  is not writable or -f is given, the
     working file is deleted without asking.

FILES
     The caller of the command must have write permission in  the
     working  directory,  read  permission  for the RCS file, and
     either read permission (for reading) or  read/write  permis-
     sion  (for  locking) in the directory which contains the RCS
     file.

     A number of temporary files are created.  A  semaphore  file
     is  created  in  the  directory  of  the RCS file to prevent
     simultaneous update.

DIAGNOSTICS
     The RCS file name, the working file name, and  the  revision
     number  retrieved are written to the diagnostic output.  The
     exit status always refers to the last file checked out,  and
     is 0 if the operation was successful, 1 otherwise.

IDENTIFICATION
     Author: Walter F. Tichy, Purdue University, West  Lafayette,
     IN, 47907.
     Revision Number: 1.5 ; Release Date: 89/10/30 .
     Copyright (C) 1982, 1988, 1989 by Walter F. Tichy.

SEE ALSO
     ci(L),   ident(L),    rcs(L),    rcsdiff(L),    rcsintro(L),
     rcsmerge(L), rlog(L), rcsfile(L)
     Walter F. Tichy, "Design, Implementation, and Evaluation  of
     a Revision Control System," in Proceedings of the 6th Inter-
     national Conference on Software  Engineering,  IEEE,  Tokyo,
     Sept. 1982.

LIMITATIONS
     The option -d  gets  confused  in  some  circumstances,  and
     accepts  no  date before 1970.  Links to the RCS and working
     files are not preserved.  There is no way  to  suppress  the
     expansion  of  keywords, except by writing them differently.
     In nroff and troff, this is  done  by  embedding  the  null-
     character `\&' into the keyword.

BUGS
     The option -j does not work for  files  that  contain  lines
     with a single `.'.