home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / rcstxi11.zip / rcstexi.110 / ci.tex < prev    next >
Text File  |  1997-03-30  |  36KB  |  981 lines

  1. @c
  2. @c ================================================================================
  3. @c                               Edition 1.1
  4. @c                      of the Texinfo-manuals for the
  5. @c                      (R)evision (C)ontrol (S)ystem
  6. @c                               Version 5.7
  7. @c
  8. @c                  (c) 1982, 1988, 1989 Walter F. Tichy.
  9. @c           (c) 1990, 1991, 1992, 1993, 1994, 1995 Paul Eggert.
  10. @c        (c) 1996, 1997 Karl Heinz Marbaise (doing converting job)
  11. @c ================================================================================
  12. @c
  13. @c Discription:
  14. @c    Discription about ci command.
  15. @c
  16. @c Authors:
  17. @c    Walter Tichy,
  18. @c    Paul Eggert,
  19. @c    Karl Heinz Marbaise (doing converting job)
  20. @c
  21. @c e-mail:
  22. @c    Internet: KHMarbaise@p69.ks.fido.de
  23. @c    Fido-net: 2:2452/117.69
  24. @c
  25. @c Bugs, question:
  26. @c    to above e-mail adress.
  27. @c
  28. @c License:
  29. @c    The "Texinfo Edition of the RCS V5.7 manuals" are free
  30. @c    software; you can redistribute it and/or modify it under
  31. @c    the terms of the GNU General Public License as published
  32. @c    by the Free Software Foundation; either version 2, or (at
  33. @c    your option) any later version.
  34. @c
  35. @c    The "Texinfo Edition of the RCS V5.7 manuals" are distributed
  36. @c    in the hope that they will be useful, but WITHOUT ANY WARRANTY;
  37. @c    without even the implied warranty of MERCHANTABILITY or
  38. @c    FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public
  39. @c    License for more details.
  40. @c
  41. @c    You should have received a copy of the GNU General Public License
  42. @c    along with the "Texinfo Edition of the RCS V5.7 manuals"; see the
  43. @c    file COPYING. If not, write to the:
  44. @c    Free Software Foundation,
  45. @c    59 Temple Place - Suite 330,
  46. @c    Boston, MA 02111-1307, USA.
  47. @c
  48. @c    See \rcstxi.110\COPYING for details.
  49. @c
  50. @c ================================================================================
  51. @c
  52. @c
  53. @c $Id: CI.TEX 1.2 1997/03/30 22:53:09 KHM Exp $
  54. @c
  55. @c =============================================================================
  56. @c ci -- check in RCS revsisions
  57. @c -----------------------------------------------------------------------------
  58. @node CheckIn,CheckOut,Synopsis,Top
  59. @chapter ci -- check in RCS revisions
  60. @cindex ci
  61. @cindex check in
  62. @menu
  63. * ciIntro::      Introduction to @code{ci}.
  64.  
  65. * ciOptions::    command line options of @code{ci}.
  66.  
  67. * ciFileNaming:: File naming.
  68. * ciExamples::   Examples.
  69. * ciFileModes::  File modes.
  70. * ciFiles::      Files.
  71. * setuid use::   Using of uid.
  72. * ciEnv::        Environment which can change
  73.                  the behaviour of @code{ci} and
  74.                  other RCS commands.
  75. * ciDiag::       Diagnostic output of @code{ci}.
  76.  
  77. @end menu
  78. @c =============================================================================
  79. @c ci -- check in RCS revsisions
  80. @c     Description
  81. @c -----------------------------------------------------------------------------
  82. @node ciIntro,ciOptions,,CheckIn
  83. @section ci description
  84.  
  85. @code{ci} stores new revisions into RCS files. Each pathname
  86. matching an RCS suffix is taken to be an RCS file. All others are
  87. assumed to be working files containing new revisions. @code{ci}
  88. deposits the contents of each working file into the corresponding
  89. RCS file. If only a working file is given, @code{ci} tries to
  90. find the corresponding RCS file in an RCS subdirectory and then
  91. in the working file's directory. For more details, @xref{ciFileNaming}
  92. below.
  93.  
  94. For @code{ci} to work, the caller's login must be on the access
  95. list, except if the access list is empty or the caller is the
  96. superuser or the owner of the file. To append a new revision to
  97. an existing branch, the tip revision on that branch must be
  98. locked by the caller.  Otherwise, only a new branch can be
  99. created.  This restriction is not enforced for the owner of the
  100. file if non-strict locking is used (see @ref{rcs}). A lock held
  101. by someone else can be broken with the @code{rcs} command.
  102.  
  103. Unless the @code{-f} option is given, @code{ci} checks whether
  104. the revision to be deposited differs from the preceding one. If
  105. not, instead of creating a new revision @code{ci} reverts to the
  106. preceding one. To revert, ordinary @code{ci} removes the working
  107. file and any lock; @code{ci -l} keeps and @code{ci -u}
  108. removes any lock, and then they both generate a new working file
  109. much as if @code{co -l} or @code{co -u} had been applied to
  110. the preceding revision. When reverting, any @code{-n} and
  111. @code{-s} options apply to the preceding revision.
  112.  
  113. For each revision deposited, @code{ci} prompts for a log message.
  114. The log message should summarize the change and must be
  115. terminated by end-of-file or by a line containing @code{.} by
  116. itself. If several files are checked in @code{ci} asks whether to
  117. reuse the previous log message. If the standard input is not a
  118. terminal, @code{ci} suppresses the prompt and uses the same log
  119. message for all files(Option @code{-m} of @code{ci}, @ref{ciOptm}).
  120.  
  121. If the RCS file does not exist, @code{ci} creates it and deposits
  122. the contents of the working file as the initial revision (default
  123. number: @code{1.1} ). The access list is initialized to empty.
  124. Instead of the log message,
  125. @code{ci} requests descriptive text
  126. (Option @code{-t} of @code{ci}, @ref{ciOptt})
  127. below).
  128.  
  129.  
  130. The number @code{rev} of the deposited revision can be given by any
  131. of the options @code{-f}, @code{-i}, @code{-I}, @code{-j},
  132. @code{-k}, @code{-l}, @code{-M}, @code{-q}, @code{-r} or @code{-u}
  133. @code{rev} can be symbolic, numeric, or mixed.
  134. Symbolic names in
  135. @code{rev} must already be defined;
  136. see the Option @code{-n} (@ref{ciOptn}) and @code{-N} (@ref{ciOptNu})
  137. options for assigning names during checkin.
  138.  
  139. If @code{rev} is @code{$}, @code{ci} determines the revision
  140. number from keyword values in the working file.
  141.  
  142. If @code{rev} begins with a period, then the default branch
  143. (normally the trunk) is prepended to it. If @code{rev} is a
  144. branch number followed by a period, then the latest revision on
  145. that branch is used.
  146.  
  147. If @code{rev} is a revision number, it must be higher than the
  148. latest one on the branch to which @code{rev} belongs, or must
  149. start a new branch.
  150.  
  151.  
  152. If @code{rev} is a branch rather than a revision number, the new
  153. revision is appended to that branch.  The level number is
  154. obtained by incrementing the tip revision number of that branch.
  155. If @code{rev} indicates a non-existing branch, that branch is
  156. created with the initial revision numbered @code{rev .1.}
  157.  
  158.  
  159. If @code{rev} is omitted, @code{ci} tries to derive the new
  160. revision number from the caller's last lock.  If the caller has
  161. locked the tip revision of a branch, the new revision is appended
  162. to that branch. The new revision number is obtained by
  163. incrementing the tip revision number. If the caller locked a
  164. non-tip revision, a new branch is started at that revision by
  165. incrementing the highest branch number at that revision. The
  166. default initial branch and level numbers are @code{1.}.
  167.  
  168.  
  169. If @code{rev} is omitted and the caller has no lock, but owns the
  170. file and locking is not set to  @code{strict}, then the revision
  171. is appended to the default branch (normally the trunk; see the
  172. option @code{-b} of @code{rcs} @ref{rcsOptb}).
  173.  
  174. Exception: On the trunk, revisions can be appended to the end, but
  175. not inserted.
  176.  
  177. @c =============================================================================
  178. @c ci -- check in RCS revsisions
  179. @c     Options
  180. @c -----------------------------------------------------------------------------
  181. @node ciOptions,ciFileNaming,ciIntro,CheckIn
  182. @section Command line options of ci
  183. @ifinfo
  184. Overview off all options which can be given to
  185.  
  186. @code{Synopsis}: ci [options] file @dots{}
  187.  
  188. @code{ci}.
  189. @end ifinfo
  190. @menu
  191. * ciOptr::     -r Revision
  192. * ciOptl::     -l lock a revision.
  193. * ciOptu::     -u unlock a revision.
  194. * ciOptf::     -f force a deposit.
  195. * ciOptk::     -k search for keyword values.
  196. * ciOptq::     -q quiet mode
  197. * ciOpti::     -i initial
  198. * ciOptj::     -j just check in
  199. * ciOptIu::    -I interacitve mode
  200. * ciOptd::     -d date
  201. * ciOptMu::    -M
  202. * ciOptm::     -m log message
  203. * ciOptn::     -n symbolic name
  204. * ciOptNu::    -N replace an existing symbolic name
  205. * ciOpts::     -s set state
  206. * ciOptt::     -t discription
  207. * ciOptTu::    -T modification time
  208. * ciOptw::     -w login
  209. * ciOptV::     -V Version of RCS; Emulate RCS Version
  210. * ciOptx::     -x Suffixes
  211. * ciOptz::     -z Time zoone for output.
  212. @end menu
  213. @c =============================================================================
  214. @c ci -- check in RCS revsisions
  215. @c     Options
  216. @c         option -r
  217. @c -----------------------------------------------------------------------------
  218. @node ciOptr,ciOptl,,ciOptions
  219. @subsection Check in revision
  220. @cindex -r
  221. @cindex revision
  222. @table @code
  223. @item -r@file{rev}
  224.  
  225. Check in revision @b{rev}.
  226.  
  227. @item -r
  228.  
  229. The bare @code{-r} option (without any revision) has an unusual
  230. meaning in @code{ci}. With other RCS  commands, a bare @code{-r}
  231. option specifies the most recent revision on the default branch,
  232. but with @code{ci}, a bare @code{-r} option reestablishes the
  233. default behavior of releasing a lock and removing the working
  234. file, and is used to override any default @code{-l} or @code{-u}
  235. options established by shell aliases or scripts.
  236.  
  237. @end table
  238.  
  239. @c =============================================================================
  240. @c ci -- check in RCS revsisions
  241. @c     Options
  242. @c         option -l
  243. @c -----------------------------------------------------------------------------
  244. @node ciOptl,ciOptu,ciOptr,ciOptions
  245. @subsection lock a revision
  246. @cindex -l
  247. @cindex lock a revision
  248. @table @code
  249. @item -l[@file{rev}]
  250.  
  251. works like @code{-r}, except it performs an additional
  252. @code{co-l} for the deposited revision.  Thus, the
  253. deposited revision is immediately checked out again and
  254. locked. This is useful for saving a revision although
  255. one wants to continue editing it after the checkin.
  256.  
  257. @end table
  258.  
  259. @c =============================================================================
  260. @c ci -- check in RCS revsisions
  261. @c     Options
  262. @c         option -u
  263. @c -----------------------------------------------------------------------------
  264. @node ciOptu,ciOptf,ciOptl,ciOptions
  265. @subsection unlock a revision
  266. @cindex -u
  267. @cindex unlock a revision
  268. @table @code
  269. @item -u[@file{rev}]
  270.  
  271. works like @code{-l}, except that the deposited revision is not
  272. locked. This lets one read the working file immediately after
  273. checkin.
  274.  
  275.  
  276. The @code{-l}, bare @code{-r}, and @code{-u} options are mutually
  277. exclusive and silently override each other. For example, @code{ci
  278. -u -r} is equivalent to @code{ci -r} because bare @code{-r}
  279. overrides @code{-u}.
  280.  
  281. @end table
  282.  
  283. @c =============================================================================
  284. @c ci -- check in RCS revsisions
  285. @c     Options
  286. @c         option -f
  287. @c -----------------------------------------------------------------------------
  288. @node ciOptf,ciOptk,ciOptu,ciOptions
  289. @subsection force a deposit
  290. @cindex -f
  291. @cindex force a deposit
  292. @table @code
  293. @item -f[@file{rev}]
  294.  
  295. forces a deposit; the new revision is deposited even it is not
  296. different from the preceding one.
  297. @end table
  298.  
  299. @c =============================================================================
  300. @c ci -- check in RCS revsisions
  301. @c     Options
  302. @c         option -k
  303. @c -----------------------------------------------------------------------------
  304. @node ciOptk,ciOptq,ciOptf,ciOptions
  305. @subsection keyword values
  306. @cindex -k
  307. @cindex keyword values
  308. @table @code
  309. @item -k[@file{rev}]
  310.  
  311. searches the working file for keyword values to determine its
  312. revision number, creation date, state, and author (see
  313. @ref{CheckOut}), and assigns these values to the deposited
  314. revision, rather than computing them locally. It also generates a
  315. default login message noting the login of the caller and the
  316. actual checkin date. This option is useful for software
  317. distribution.  A revision that is sent to several sites should be
  318. checked in with the @code{-k} option at these sites to preserve
  319. the original number, date, author, and state. The extracted
  320. keyword values and the default log message can be overridden with
  321. the options @code{-d}, @code{-m}, @code{-s}, @code{-w}, and any
  322. option that carries a revision number.
  323. @end table
  324.  
  325. @c =============================================================================
  326. @c ci -- check in RCS revsisions
  327. @c     Options
  328. @c         option -q
  329. @c -----------------------------------------------------------------------------
  330. @node ciOptq,ciOpti,ciOptk,ciOptions
  331. @subsection quiet
  332. @cindex -q
  333. @cindex quiet
  334. @cindex diagnostic
  335. @table @code
  336. @item -q[@file{rev}]
  337.  
  338. quiet mode; diagnostic output is not printed. A revision that is
  339. not different from the preceding one is not deposited, unless
  340. @code{-f} is given.
  341.  
  342. @end table
  343.  
  344. @c =============================================================================
  345. @c ci -- check in RCS revsisions
  346. @c     Options
  347. @c         option -i
  348. @c -----------------------------------------------------------------------------
  349. @node ciOpti,ciOptj,ciOptq,ciOptions
  350. @subsection initial check in
  351. @cindex -i
  352. @cindex initial checkin
  353. @table @code
  354. @item -i[@file{rev}]
  355.  
  356. initial checkin; report an error if the RCS file already exists.
  357. This avoids race conditions in certain applications.
  358.  
  359. @end table
  360.  
  361. @c =============================================================================
  362. @c ci -- check in RCS revsisions
  363. @c     Options
  364. @c         option -j
  365. @c -----------------------------------------------------------------------------
  366. @node ciOptj,ciOptIu,ciOpti,ciOptions
  367. @subsection just check in
  368. @cindex -j
  369. @cindex just checkin
  370. @table @code
  371. @item -j[@file{rev}]
  372.  
  373. just checkin and do not initialize;
  374. report an error if the RCS file does not already exist.
  375.  
  376. @end table
  377.  
  378. @c =============================================================================
  379. @c ci -- check in RCS revsisions
  380. @c     Options
  381. @c         option -I
  382. @c -----------------------------------------------------------------------------
  383. @node ciOptIu,ciOptd,ciOptj,ciOptions
  384. @subsection interactive mode
  385. @cindex -I
  386. @cindex interactive mode
  387. @cindex interactive
  388. @table @code
  389. @item -I[@file{rev}]
  390.  
  391. interactive mode; the user is prompted and questioned
  392. even if the standard input is not a terminal.
  393.  
  394. @end table
  395.  
  396. @c =============================================================================
  397. @c ci -- check in RCS revsisions
  398. @c     Options
  399. @c         option -d
  400. @c -----------------------------------------------------------------------------
  401. @node ciOptd,ciOptMu,ciOptIu,ciOptions
  402. @subsection date
  403. @cindex -d
  404. @cindex date
  405. @table @code
  406. @item -d[@file{date}]
  407.  
  408. uses @code{date} for the checkin date and time. The @code{date}
  409. is specified in free format as explained in @code{co} (@xref{CheckOut}).
  410. This is useful for lying about the checkin date, and for @code{-k} if
  411. no date is available. If @code{date} is empty, the working file's
  412. time of last modification is used.
  413.  
  414. @end table
  415.  
  416. @c =============================================================================
  417. @c ci -- check in RCS revsisions
  418. @c     Options
  419. @c         option -M
  420. @c -----------------------------------------------------------------------------
  421. @node ciOptMu,ciOptm,ciOptd,ciOptions
  422. @subsection modification time
  423. @cindex -M
  424. @cindex modification time
  425. @table @code
  426. @item -M[@file{rev}]
  427.  
  428. Set the modification time on any new working file to be the date
  429. of the retrieved revision. For example, @code{ci -d -M -u f} does
  430. not alter @file{f} 's modification time, even if @file{f}'s
  431. contents change due to keyword substitution. Use this option with
  432. care; it can confuse @code{MAKE}.
  433.  
  434. @end table
  435.  
  436. @c =============================================================================
  437. @c ci -- check in RCS revsisions
  438. @c     Options
  439. @c         option -m
  440. @c -----------------------------------------------------------------------------
  441. @node ciOptm,ciOptn,ciOptMu,ciOptions
  442. @subsection log message
  443. @cindex -m
  444. @cindex log message
  445. @table @code
  446. @item -m[@file{msg}]
  447.  
  448. uses the string @code{msg} as the log message for all revisions
  449. checked in. By convention, log messages that start with @code{#}
  450. are comments and are ignored by programs like GNU Emacs's
  451. @code{vc} package. Also, log messages that start with
  452. @code{@{ clumpname @}} (followed by white space) are meant to be
  453. clumped together if possible, even if they are associated with
  454. different files; the @code{@{ clumpname @}} label is used only
  455. for clumping, and is not considered to be part of the log message
  456. itself.
  457.  
  458. @end table
  459.  
  460. @c =============================================================================
  461. @c ci -- check in RCS revsisions
  462. @c     Options
  463. @c         option -n
  464. @c -----------------------------------------------------------------------------
  465. @node ciOptn,ciOptNu,ciOptm,ciOptions
  466. @subsection symbolic name
  467. @cindex -n
  468. @cindex symbolic name
  469. @cindex tag
  470. @table @code
  471. @item -n[@file{name}]
  472.  
  473. assigns the symbolic name @code{name} to the number of the
  474. checked-in revision. @code{ci} prints an error message if
  475. @code{name} is already assigned to another number.
  476.  
  477. @end table
  478.  
  479. @c =============================================================================
  480. @c ci -- check in RCS revsisions
  481. @c     Options
  482. @c         option -N
  483. @c -----------------------------------------------------------------------------
  484. @node ciOptNu,ciOpts,ciOptn,ciOptions
  485. @subsection replace symbolic name
  486. @cindex -N
  487. @cindex override symbolic name
  488. @table @code
  489. @item -N[@file{name}]
  490.  
  491. same as @code{-n}, except that it overrides a previous assignment
  492. of @code{name}.
  493.  
  494. @end table
  495.  
  496. @c =============================================================================
  497. @c ci -- check in RCS revsisions
  498. @c     Options
  499. @c         option -s
  500. @c -----------------------------------------------------------------------------
  501. @node ciOpts,ciOptt,ciOptNu,ciOptions
  502. @subsection states
  503. @cindex -s
  504. @cindex states
  505. @table @code
  506. @item -s[@file{state}]
  507.  
  508. sets the state of the checked-in revision to the identifier
  509. @code{state}. The default state is @code{Exp}.
  510.  
  511. @end table
  512.  
  513. @c =============================================================================
  514. @c ci -- check in RCS revsisions
  515. @c     Options
  516. @c         option -t
  517. @c -----------------------------------------------------------------------------
  518. @node ciOptt,ciOptTu,ciOpts,ciOptions
  519. @subsection description
  520. @cindex -t
  521. @cindex -t-
  522. @cindex description
  523. @table @code
  524. @item -t@file{file}
  525.  
  526. writes descriptive text from the contents of the named
  527. @file{file}
  528. into the RCS file, deleting the existing text.
  529. The @file{file} cannot begin with @code{-}.
  530.  
  531. @item -t-@file{string}
  532.  
  533. Write descriptive text from the @file{string} into the RCS file,
  534. deleting the existing text.
  535.  
  536. The @code{-t} option, in both its forms, has effect only during
  537. an initial checkin; it is silently ignored otherwise.
  538.  
  539. During the initial checkin, if @code{-t} is not given, @code{ci}
  540. obtains the text from standard input, terminated by end-of-file
  541. or by a line containing @code{.} by itself. The user is prompted
  542. for the text if interaction is possible; see optiom @code{-I}
  543. of @code{ci}(@xref{ciOptIu}).
  544.  
  545. For backward compatibility with older versions of RCS, a bare
  546. @code{-t} option is ignored.
  547.  
  548. @end table
  549.  
  550. @c =============================================================================
  551. @c ci -- check in RCS revsisions
  552. @c     Options
  553. @c         option -T
  554. @c -----------------------------------------------------------------------------
  555. @node ciOptTu,ciOptw,ciOptt,ciOptions
  556. @subsection modification time
  557. @cindex -T
  558. @cindex modification time
  559. @table @code
  560. @item -T
  561.  
  562. Set the RCS file's modification time to the new revision's time
  563. if the former precedes the latter and there is a new revision;
  564. preserve the RCS file's modification time otherwise. If you have
  565. locked a revision, @code{ci} usually updates the RCs file's
  566. modification time to the current time, because the lock is stored
  567. in the RCS file and removing the lock requires changing the RCS
  568. file. This can create an RCS file newer than the working file in
  569. one of two ways: first, @code{ci -M} can create a working file
  570. with a date before the current time; second, when reverting to
  571. the previous revision the RCS file can change while the working
  572. file remains unchanged. These two cases can cause excessive
  573. recompilation caused by a @code{MAKE} dependency of the working
  574. file on the RCS file. The @code{-T} option inhibits this
  575. recompilation by lying about the RCS file's date. Use this option
  576. with care; it can suppress recompilation even when a checkin of
  577. one working file should affect another working file associated
  578. with the same RCS file. For example, suppose the RCS file's time
  579. is 01:00, the (changed) working file's time is 02:00, some other
  580. copy of the working file has a time of 03:00, and the current
  581. time is 04:00. Then @code{ci -d -T} sets the RCS file's time to
  582. 02:00 instead of the usual 04:00; this causes @code{MAKE} to
  583. think (incorrectly) that the other copy is newer than the RCs
  584. file.
  585.  
  586. @end table
  587.  
  588. @c =============================================================================
  589. @c ci -- check in RCS revsisions
  590. @c     Options
  591. @c         option -w
  592. @c -----------------------------------------------------------------------------
  593. @node ciOptw,ciOptV,ciOptTu,ciOptions
  594. @subsection login
  595. @cindex -w
  596. @cindex login
  597. @table @code
  598. @item -w@file{login}
  599.  
  600. uses @code{login} for the author field of the deposited revision.
  601. Useful for lying about the author, and for @code{-k} if no author
  602. is available.
  603.  
  604. @end table
  605.  
  606. @c =============================================================================
  607. @c ci -- check in RCS revsisions
  608. @c     Options
  609. @c         option -V, -Vn
  610. @c -----------------------------------------------------------------------------
  611. @node ciOptV,ciOptx,ciOptw,ciOptions
  612. @subsection version and emulation
  613. @cindex -V
  614. @cindex emulate RCS Version
  615. @cindex print RCS Version
  616. @table @code
  617. @item -V
  618.  
  619. Print RCS's version number.
  620. @item -V@file{n}
  621.  
  622. Emulate RCS version @code{n}. @xref{coOptV}
  623.  
  624. @end table
  625.  
  626. @c =============================================================================
  627. @c ci -- check in RCS revsisions
  628. @c     Options
  629. @c         option -x
  630. @c -----------------------------------------------------------------------------
  631. @node ciOptx,ciOptz,ciOptV,ciOptions
  632. @subsection suffixes
  633. @cindex -x
  634. @cindex suffixes
  635. @table @code
  636. @item -x@file{suffixes}
  637.  
  638. specifies the suffixes for RCS files. A nonempty suffix matches
  639. any pathname ending in the suffix. An empty suffix matches any
  640. pathname of the form @code{RCS/@b{path}} or
  641. @code{path1/RCS/path2}. The @code{-x} option can specify a list
  642. of suffixes separated by @code{.} For example, @code{-x,v/}
  643. specifies two suffixes: @code{,v} and the empty suffix. If two or
  644. more suffixes are specified, they are tried in order when looking
  645. for an RCS file; the first one that works is used for that file.
  646. If no RCS file is found but an RCS file can be created, the
  647. suffixes are tried in order to determine the new RCS file's name.
  648. The default for @code{suffixes} is installation-dependent;
  649. normally it is @code{,v/} for hosts like Unix that permit commas
  650. in filenames, and is empty (i.e. just the empty suffix) for other
  651. hosts.
  652.  
  653. @end table
  654.  
  655. @c =============================================================================
  656. @c ci -- check in RCS revsisions
  657. @c     Options
  658. @c         option -z
  659. @c -----------------------------------------------------------------------------
  660. @node ciOptz,,ciOptx,ciOptions
  661. @subsection time zoone
  662. @cindex -z
  663. @cindex zoone
  664. @cindex time zoone
  665. @cindex TZ
  666. @table @code
  667. @item -z@file{zoone}
  668.  
  669. specifies the date output format in keyword substitution, and
  670. specifies the default time zone for @code{date} in the
  671. @code{-d@file{date}} option. The @file{zoone} should be empty, a
  672. numeric UTC offset, or the special string @file{LT} for local
  673. time. The default is an empty @file{zoone}, which uses the
  674. traditional RCS format of UTC without any time zone indication and
  675. with slashes separating the parts of the date; otherwise, times
  676. are output in ISO 8601 format with time zone indication. For
  677. example, if local time is January 11, 1990, 8pm Pacific Standard
  678. Time, eight hours west of UTC, then the time is output as
  679. follows:
  680.  
  681. @example
  682. @group
  683. @code{Option}   @code{time output}
  684. @code{-z}       @code{1990/01/11 04:00:00}       (default)
  685. @code{-zLT}     @code{1990-01-11 20:00:00-0800}
  686. @code{-z+0530}  @code{1990-01-11 09:30:00+0530}
  687. @end group
  688. @end example
  689.  
  690.  
  691. This option
  692. does not affect dates stored in RCS files, which are always UTC.
  693.  
  694. @end table
  695.  
  696. @c =============================================================================
  697. @c ci -- check in RCS revsisions
  698. @c     FILE NAMING
  699. @c -----------------------------------------------------------------------------
  700. @node ciFileNaming,ciExamples,ciOptions,CheckIn
  701. @section FILE NAMING
  702. Pairs of RCS files and working files can be specified in three
  703. ways (see also the example section).
  704.  
  705. @enumerate
  706. @item Both the file and the working file are given.
  707. The RCS pathname is of the form @code{path1/workfileX}
  708. and the working pathname is of the form
  709. @code{path2/workfile} where @code{path1/} and @code{path2/}
  710. are (possibly different or empty) paths, @code{workfile}
  711. is a filename, and @code{X} is an RCs suffix. If @code{X}
  712. is empty, @code{path1/} must start with @code{RCS/} or
  713. must contain @code{/RCS/}.
  714.  
  715.  
  716. @item Only the RCS file is given.  Then the working file is created
  717. in the current directory and its name is derived from the name of
  718. the RCS file by removing @code{path1/} and the suffix @code{X}.
  719.  
  720. @item Only the working file is given. Then @code{ci} considers each
  721. RCS suffix @code{X} in turn, looking for an RCS file of the form
  722. @code{path2/RCS/workfileX} or (if the former is not found and
  723. @code{X} is nonempty) @code{path2/workfileX}.
  724.  
  725. @end enumerate
  726.  
  727. If the RCS file is specified without a path in 1) and 2),
  728. @code{ci} looks for the RCS file first in the directory
  729. @code{./RCS} and then in the current directory.
  730.  
  731.  
  732. @code{ci} reports an error if an attempt to open an RCS file
  733. fails for an unusual reason, even if the RCS file's pathname is
  734. just one of several possibilities. For example, to suppress use
  735. of RCS commands in a directory @code{d} , create a regular file
  736. named @code{d/RCS} so that casual attempts to use RCS commands in
  737. @code{d} fail because @code{d/RCS} is not a directory.
  738.  
  739. @c =============================================================================
  740. @c ci -- check in RCS revsisions
  741. @c     EXAMPLES
  742. @c -----------------------------------------------------------------------------
  743. @node ciExamples,ciFileModes,ciFileNaming,CheckIn
  744. @section Examples
  745.  
  746. Suppose @code{,v} is an RCS suffix and the current directory
  747. contains a subdirectory @code{RCS} with an RCS file
  748. @file{io.c,v}. Then each of the following commands check in a
  749. copy of @file{io.c} into @file{RCS/io.c,v} as the latest
  750. revision, removing @file{io.c}.
  751.  
  752. @example
  753. @w{ci  io.c}
  754. @w{ci  RCS/io.c,v}
  755. @w{ci  io.c,v}
  756. @w{ci  io.c RCS/io.c,v}
  757. @w{ci  io.c io.c,v}
  758. @w{ci  RCS/io.c,v  io.c}
  759. @w{ci  io.c,v  io.c}
  760. @end example
  761.  
  762. Suppose instead that the empty suffix is an RCS suffix and the
  763. current directory contains a subdirectory @code{RCS} with an RCS
  764. file @code{io.c}. The each of the following commands checks in a
  765. new revision.
  766.  
  767. @example
  768. @w{ci  io.c}
  769. @w{ci  RCS/io.c}
  770. @w{ci  io.c  RCS/io.c}
  771. @w{ci  RCS/io.c  io.c}
  772. @end example
  773.  
  774. @c =============================================================================
  775. @c ci -- check in RCS revsisions
  776. @c     File modes
  777. @c -----------------------------------------------------------------------------
  778. @node ciFileModes,ciFiles,ciExamples,CheckIn
  779. @section File Modes
  780. An RCS file created by @code{ci} inherits the read and execute
  781. permissions from the working file.  If the RCS file exists
  782. already, @code{ci} preserves its read and execute permissions.
  783. @code{ci} always turns off all write permissions of RCS files.
  784.  
  785. @c =============================================================================
  786. @c ci -- check in RCS revsisions
  787. @c     Files
  788. @c -----------------------------------------------------------------------------
  789. @node ciFiles,setuid use,ciFileModes,CheckIn
  790. @section Files
  791. Temporary files are created in the directory containing the
  792. working file, and also in the temporary directory (@xref{ciEnv}
  793. under @ref{coEnv}). A semaphore file or files
  794. are created in the directory containing the RCS file. With a
  795. nonempty suffix, the semaphore names begin with the first
  796. character of the suffix; therefore, do not specify an suffix
  797. whose first character could be that of a working filename. With
  798. an empty suffix, the semaphore names end with @code{_} so working
  799. filenames should not end in @code{_}
  800.  
  801.  
  802. @code{ci} never changes an RCS or working file. Normally,
  803. @code{ci} unlinks the file and creates a new one; but instead of
  804. breaking a chain of one or more symbolic links to an RCS file, it
  805. unlinks the destination file instead. Therefore, @code{ci} breaks
  806. any hard or symbolic links to any working file it changes; and
  807. hard links to RCS files are ineffective, but symbolic links to
  808. RCS files are preserved.
  809.  
  810.  
  811. The effective user must be able to search and write the directory
  812. containing the RCS file. Normally, the real user must be able to
  813. read the RCS and working files and to search and write the
  814. directory containing the working file; however, some older hosts
  815. cannot easily switch between real and effective users, so on
  816. these hosts the effective user is used for all accesses. The
  817. effective user is the same as the real user unless your copies of
  818. @code{ci} and @code{co} have setuid privileges. As described in
  819. the next section, these privileges yield extra security if the
  820. effective user owns all RCS files and directories, and if only
  821. the effective user can write RCS directories.
  822.  
  823.  
  824. Users can control access to RCS files by setting the permissions
  825. of the directory containing the files; only users with write
  826. access to the directory can use RCS commands to change its RCS
  827. files. For example, in hosts that allow a user to belong to
  828. several groups, one can make a group's RCS directories writable
  829. to that group only. This approach suffices for informal projects,
  830. but it means that any group member can arbitrarily change the
  831. group's RCS files, and can even remove them entirely. Hence more
  832. formal projects sometimes distinguish between an RCS
  833. administrator, who can change the RCS files at will, and other
  834. project members, who can check in new revisions but cannot
  835. otherwise change the RCS files.
  836.  
  837. @c =============================================================================
  838. @c ci -- check in RCS revsisions
  839. @c     setuid use
  840. @c -----------------------------------------------------------------------------
  841. @node setuid use,ciEnv,ciFiles,CheckIn
  842. @section Setuid use
  843. To prevent anybody but their RCS administrator from deleting revisions,
  844. a set of users can employ setuid privileges as follows.
  845.  
  846. @itemize @bullet{}
  847. @item Check that the host supports RCS setuid use.
  848. Consult a trustworthy expert if there are any doubts.
  849. It is best if the @code{seteuid}
  850. system call works as described in Posix 1003.1a Draft 5,
  851. because RCS can switch back and forth easily
  852. between real and effective users, even if the real user is
  853. @code{root}.
  854. If not, the second best is if the @code{setuid}
  855. system call supports saved setuid
  856. (the @code{_POSIX_SAVED_IDS} behavior of Posix 1003.1-1990);
  857. this fails only if the real or effective user is
  858. @code{root}.
  859. If RCS detects any failure in setuid, it quits immediately.
  860.  
  861. @item Choose a user @code{A}
  862. to serve as RCS administrator for the set of users.
  863. Only @code{A} can invoke the @code{rcs}
  864. command on the users' RCS files.
  865. @code{A} should not be @code{root}
  866. or any other user with special powers.
  867. Mutually suspicious sets of users should use different administrators.
  868.  
  869. @item Choose a pathname @code{B} to be a directory of files to
  870. be executed by the users.
  871.  
  872. @item Have @code{A} set up @code{B} to contain copies of
  873. @code{ci} and @code{co} that are setuid to @code{A}
  874. by copying the commands from their standard installation directory
  875. @code{D} as follows:
  876.  
  877.  
  878. @example
  879. @group
  880. mkdir @file{B}
  881. cp @file{D}/c[io] @file{B}
  882. chmod go-w,u+s @file{B}/c[io]
  883. @end group
  884. @end example
  885.  
  886.  
  887. @item Have each user prepend @code{B} to their path as follows:
  888.  
  889. @example
  890. @group
  891. PATH=@file{B}:$PATH; export PATH # ordinary shell
  892. set path=(@file{B} $path)        # C - shell
  893. @end group
  894. @end example
  895.  
  896.  
  897. @item Have @code{A} create each RCS directory @code{R}
  898. with write access only to @code{A}
  899. as follows:
  900.  
  901. @example
  902. @group
  903. mkdir @file{R}
  904. chmod go-w @file{R}
  905. @end group
  906. @end example
  907.  
  908.  
  909. @item If you want to let only certain users read the RCS files,
  910. put the users into a group @code{G},
  911. and have @code{A} further protect the RCs directory as follows:
  912.  
  913.  
  914. @example
  915. @group
  916. chgrp @file{G}  @file{R}
  917. chmod g-w, o-rwx  @file{R}
  918. @end group
  919. @end example
  920.  
  921. @item Have @code{A} copy old RCS files (if any) into
  922. @code{R}, to ensure that @code{A} owns them.
  923.  
  924. @item An RCS file's access list limits who can check in and lock revisions.
  925. The default access list is empty,
  926. which grants checkin access to anyone who can read the RCS file.
  927. If you want limit checkin access,
  928. have @code{A} invoke @code{rcs -a} on the file; see @ref{rcs}
  929. In particular, @code{rcs -e -a@file{A}} limits access to just
  930. @code{A}.
  931.  
  932. @item Have @code{A} initialize any new RCS files with
  933. @code{rcs -i} before initial checkin, adding the
  934. @code{-a} option if you want to limit checkin access.
  935.  
  936. @item Give setuid privileges only to @code{ci}, @code{co},
  937. and @code{rcsclean}; do not give them to @code{rcs}
  938. or to any other command.
  939.  
  940. @item Do not use other setuid commands to invoke RCS commands;
  941. setuid is trickier than you think!
  942.  
  943. @end itemize
  944.  
  945. @c =============================================================================
  946. @c ci -- check in RCS revsisions
  947. @c     Environment
  948. @c -----------------------------------------------------------------------------
  949. @node ciEnv,ciDiag,setuid use,CheckIn
  950. @section Environment
  951. @table @code
  952.  
  953. @item RCSINIT
  954. options prepended to the argument list, separated by spaces.
  955. A backslash escapes spaces within an option.
  956. The @code{RCSINIT} options are prepended to the argument lists
  957. of most RCS commands. Useful @code{RCSINIT}
  958. options include @code{-q}, @code{-V}, @code{-x} and @code{-z}.
  959.  
  960. @item TMPDIR
  961. Name of the temporary directory.
  962. If not set, the environment variables
  963. @code{TMP} and @code{TEMP}
  964. are inspected instead and the first value found is taken;
  965. if none of them are set,
  966. a host-dependent default is used, typically
  967. @code{/tmp}.
  968. @end table
  969.  
  970. @c =============================================================================
  971. @c ci -- check in RCS revsisions
  972. @c     Diagnostics
  973. @c -----------------------------------------------------------------------------
  974. @node ciDiag,,ciEnv,CheckIn
  975. @section Diagnostics
  976. For each revision, @code{ci} prints the RCS file,
  977. the working file, and the number of both the deposited and the
  978. preceding revision. The exit status is zero if and only if all
  979. operations were successful.
  980.  
  981.