/contrib/cvs/contrib/cvshelp.man

https://bitbucket.org/freebsd/freebsd-head/ · Unknown · 561 lines · 561 code · 0 blank · 0 comment · 0 complexity · d5dba182e52059d18d578cec4adeda4f MD5 · raw file

  1. .\" Contributed by Lowell Skoog <fluke!lowell@uunet.uu.net>
  2. .\" Full space in nroff; half space in troff
  3. .de SP
  4. .if n .sp
  5. .if t .sp .5
  6. ..
  7. .\" Start a command example
  8. .de XS
  9. .SP
  10. .in +.5i
  11. .ft B
  12. .nf
  13. ..
  14. .\" End a command example
  15. .de XE
  16. .fi
  17. .ft P
  18. .in -.5i
  19. .SP
  20. ..
  21. .TH CVSHELP LOCAL "17 March 1991" FLUKE
  22. .SH NAME
  23. cvshelp \- advice on using the Concurrent Versions System
  24. .SH DESCRIPTION
  25. This man page is based on experience using CVS.
  26. It is bound to change as we gain more experience.
  27. If you come up with better advice than is found here,
  28. contact the Software Technology
  29. Group and we will add it to this page.
  30. .SS "Getting Started"
  31. Use the following steps to prepare to use CVS:
  32. .TP
  33. \(bu
  34. Take a look at the CVS manual page to see what it can do for you, and
  35. if it fits your environment (or can possibly be made to fit your
  36. environment).
  37. .XS
  38. man cvs
  39. .XE
  40. If things look good, continue on...
  41. .TP
  42. \(bu
  43. Setup the master source repository. Choose a directory with
  44. ample disk space available for source files. This is where the RCS
  45. `,v' files will be stored. Say you choose
  46. .B /src/master
  47. as the root
  48. of your source repository. Make the
  49. .SB CVSROOT.adm
  50. directory in the root of the source repository:
  51. .XS
  52. mkdir /src/master/CVSROOT.adm
  53. .XE
  54. .TP
  55. \(bu
  56. Populate this directory with the
  57. .I loginfo
  58. and
  59. .I modules
  60. files from the
  61. .B "/usr/doc/local/cvs"
  62. directory. Edit these files to reflect your local source repository
  63. environment \- they may be quite small initially, but will grow as
  64. sources are added to your source repository. Turn these files into
  65. RCS controlled files:
  66. .XS
  67. cd /src/master/CVSROOT.adm
  68. ci \-m'Initial loginfo file' loginfo
  69. ci \-m'Initial modules file' modules
  70. .XE
  71. .TP
  72. \(bu
  73. Run the command:
  74. .XS
  75. mkmodules /src/master/CVSROOT.adm
  76. .XE
  77. This will build the
  78. .BR ndbm (3)
  79. file for the modules database.
  80. .TP
  81. \(bu
  82. Remember to edit the
  83. .I modules
  84. file manually when sources are checked
  85. in with
  86. .B checkin
  87. or CVS
  88. .BR add .
  89. A copy of the
  90. .I modules
  91. file for editing can be retrieved with the command:
  92. .XS
  93. cvs checkout CVSROOT.adm
  94. .XE
  95. .TP
  96. \(bu
  97. Have all users of the CVS system set the
  98. .SM CVSROOT
  99. environment variable appropriately to reflect the placement of your
  100. source repository. If the above example is used, the following
  101. commands can be placed in a
  102. .I .login
  103. or
  104. .I .profile
  105. file:
  106. .XS
  107. setenv CVSROOT /src/master
  108. .XE
  109. for csh users, and
  110. .XS
  111. CVSROOT=/src/master; export CVSROOT
  112. .XE
  113. for sh users.
  114. .SS "Placing Locally Written Sources Under CVS Control"
  115. Say you want to place the `whizbang' sources under
  116. CVS control. Say further that the sources have never
  117. been under revision control before.
  118. .TP
  119. \(bu
  120. Move the source hierarchy (lock, stock, and barrel)
  121. into the master source repository:
  122. .XS
  123. mv ~/whizbang $CVSROOT
  124. .XE
  125. .TP
  126. \(bu
  127. Clean out unwanted object files:
  128. .XS
  129. cd $CVSROOT/whizbang
  130. make clean
  131. .XE
  132. .TP
  133. \(bu
  134. Turn every file in the hierarchy into an RCS controlled file:
  135. .XS
  136. descend \-f 'ci \-t/dev/null \-m"Placed under CVS control" \-nV\fR\fIx\fR\fB_\fR\fIy\fR\fB *'
  137. .XE
  138. In this example, the initial release tag is \fBV\fIx\fB_\fIy\fR,
  139. representing version \fIx\fR.\fIy\fR.
  140. .LP
  141. You can use CVS on sources that are already under RCS control.
  142. The following example shows how.
  143. In this example, the source package is called `skunkworks'.
  144. .TP
  145. \(bu
  146. Move the source hierarchy into the master source
  147. repository:
  148. .XS
  149. mv ~/skunkworks $CVSROOT
  150. .XE
  151. .TP
  152. \(bu
  153. Clean out unwanted object files:
  154. .XS
  155. cd $CVSROOT/skunkworks
  156. make clean
  157. .XE
  158. .TP
  159. \(bu
  160. Clean out unwanted working files, leaving only the RCS `,v' files:
  161. .XS
  162. descend \-r rcsclean
  163. .XE
  164. Note: If any working files have been checked out and changed,
  165. .B rcsclean
  166. will fail. Check in the modified working files
  167. and run the command again.
  168. .TP
  169. \(bu
  170. Get rid of
  171. .SB RCS
  172. subdirectories. CVS does not use them.
  173. .XS
  174. descend \-r \-f 'mv RCS/*,v .'
  175. descend \-r \-f 'rmdir RCS'
  176. .XE
  177. .TP
  178. \(bu
  179. Delete any unwanted files that remain in the source hierarchy. Then
  180. make sure all files are under RCS control:
  181. .XS
  182. descend \-f 'ci \-t/dev/null \-m"Placed under CVS control" \-n\fR\fItag\fR\fB *'
  183. .XE
  184. .I tag
  185. is the latest symbolic revision tag that you applied to your package
  186. (if any). Note: This command will probably generate lots of error
  187. messages (for directories and existing RCS files) that you can
  188. ignore.
  189. .SS "Placing a Third-Party Source Distribution Under CVS Control"
  190. The
  191. .B checkin
  192. command checks third-party sources into CVS. The
  193. difference between third-party sources and locally
  194. written sources is that third-party sources must be checked into a
  195. separate branch (called the
  196. .IR "vendor branch" )
  197. of the RCS tree. This makes it possible to merge local changes to
  198. the sources with later releases from the vendor.
  199. .TP
  200. \(bu
  201. Save the original distribution kit somewhere. For example, if the
  202. master source repository is
  203. .B /src/master
  204. the distribution kit could be saved in
  205. .BR /src/dist .
  206. Organize the distribution directory so that each release
  207. is clearly identifiable.
  208. .TP
  209. \(bu
  210. Unpack the package in a scratch directory, for example
  211. .BR ~/scratch .
  212. .TP
  213. \(bu
  214. Create a repository for the package.
  215. In this example, the package is called `Bugs-R-Us 4.3'.
  216. .XS
  217. mkdir $CVSROOT/bugs
  218. .XE
  219. .TP
  220. \(bu
  221. Check in the unpacked files:
  222. .XS
  223. cd ~/scratch
  224. checkin \-m 'Bugs-R-Us 4.3 distribution' bugs VENDOR V4_3
  225. .XE
  226. There is nothing magic about the tag `VENDOR', which is applied to
  227. the vendor branch. You can use whatever tag you want. `VENDOR' is a
  228. useful convention.
  229. .TP
  230. \(bu
  231. Never modify vendor files before checking them in.
  232. Check in the files
  233. .I exactly
  234. as you unpacked them.
  235. If you check in locally modified files, future vendor releases may
  236. wipe out your local changes.
  237. .SS "Working With CVS-Controlled Sources"
  238. To use or edit the sources, you must check out a private copy.
  239. For the following examples, the master files are assumed to reside in
  240. .BR "$CVSROOT/behemoth" .
  241. The working directory is
  242. .BR "~/work" .
  243. See
  244. .BR cvs (local)
  245. for more details on the commands mentioned below.
  246. .TP
  247. .I "To Check Out Working Files
  248. Use CVS
  249. .BR checkout :
  250. .XS
  251. cd ~/work
  252. cvs checkout behemoth
  253. .XE
  254. There is nothing magic about the working directory. CVS will check
  255. out sources anywhere you like. Once you have a working copy of the
  256. sources, you can compile or edit them as desired.
  257. .TP
  258. .I "To Display Changes You Have Made"
  259. Use CVS
  260. .BR diff
  261. to display detailed changes, equivalent to
  262. .BR rcsdiff (local).
  263. You can also use
  264. .BR cvscheck (local)
  265. to list files added, changed, and removed in
  266. the directory, but not yet
  267. .BR commit ted.
  268. You must be in a directory containing working files.
  269. .TP
  270. .I "To Display Revision Information"
  271. Use CVS
  272. .BR log ,
  273. which is equivalent to
  274. .BR rlog (local).
  275. You must be in a directory containing working files.
  276. .TP
  277. .I "To Update Working Files"
  278. Use CVS
  279. .BR update
  280. in a directory containing working files.
  281. This command brings your working files up
  282. to date with changes checked into the
  283. master repository since you last checked out or updated
  284. your files.
  285. .TP
  286. .I "To Check In Your Changes"
  287. Use CVS
  288. .BR commit
  289. in a directory containing working files.
  290. This command checks your changes into the master repository.
  291. You can specify files by name or use
  292. .XS
  293. cvs commit \-a
  294. .XE
  295. to
  296. .B commit
  297. all the files you have changed.
  298. .TP
  299. .I "To Add a File"
  300. Add the file to the working directory.
  301. Use CVS
  302. .B add
  303. to mark the file as added.
  304. Use CVS
  305. .B commit
  306. to add the file to the master repository.
  307. .TP
  308. .I "To Remove a File"
  309. Remove the file from the working directory.
  310. Use CVS
  311. .B remove
  312. to mark the file as removed.
  313. Use CVS
  314. .B commit
  315. to move the file from its current location in the master repository
  316. to the CVS
  317. .IR Attic
  318. directory.
  319. .TP
  320. .I "To Add a Directory"
  321. Add the directory to the working directory.
  322. Use CVS
  323. .B add
  324. to add the directory to the master repository.
  325. .TP
  326. .I "To Remove a Directory"
  327. .br
  328. You shouldn't remove directories under CVS. You should instead remove
  329. their contents and then prune them (using the
  330. .B \-f
  331. and
  332. .B \-p
  333. options) when you
  334. .B checkout
  335. or
  336. .B update
  337. your working files.
  338. .TP
  339. .I "To Tag a Release"
  340. Use CVS
  341. .B tag
  342. to apply a symbolic tag to the latest revision of each file in the
  343. master repository. For example:
  344. .XS
  345. cvs tag V2_1 behemoth
  346. .XE
  347. .TP
  348. .I "To Retrieve an Exact Copy of a Previous Release"
  349. During a CVS
  350. .B checkout
  351. or
  352. .BR update ,
  353. use the
  354. .B \-r
  355. option to retrieve revisions associated with a symbolic tag.
  356. Use the
  357. .B \-f
  358. option to ignore all RCS files that do not contain the
  359. tag.
  360. Use the
  361. .B \-p
  362. option to prune directories that wind up empty because none
  363. of their files matched the tag. Example:
  364. .XS
  365. cd ~/work
  366. cvs checkout \-r V2_1 \-f \-p behemoth
  367. .XE
  368. .SS "Logging Changes"
  369. It is a good idea to keep a change log together with the
  370. sources. As a minimum, the change log should name and describe each
  371. tagged release. The change log should also be under CVS control and
  372. should be tagged along with the sources.
  373. .LP
  374. .BR cvslog (local)
  375. can help. This command logs
  376. changes reported during CVS
  377. .B commit
  378. operations. It automatically
  379. updates a change log file in your working directory. When you are
  380. finished making changes, you (optionally) edit the change log file and
  381. then commit it to the master repository.
  382. .LP
  383. Note: You must edit the change log to describe a new release
  384. and
  385. .B commit
  386. it to the master repository
  387. .I before
  388. .BR tag ging
  389. the release using CVS. Otherwise, the release description will not be
  390. included in the tagged package.
  391. .LP
  392. See
  393. .BR cvslog (local)
  394. for more information.
  395. .SS "Merging a Subsequent Third-Party Distribution"
  396. The initial steps in this process are identical to placing a
  397. third-party distribution under CVS for the first time: save the
  398. distribution kit and unpack the package in a scratch directory. From
  399. that point the steps diverge.
  400. The following example considers release 5.0 of the
  401. Bugs-R-Us package.
  402. .TP
  403. \(bu
  404. Check in the sources after unpacking them:
  405. .XS
  406. cd ~/scratch
  407. checkin \-m 'Bugs-R-Us 5.0 distribution' bugs VENDOR V5_0 \\
  408. | tee ~/WARNINGS
  409. .XE
  410. It is important to save the output of
  411. .B checkin
  412. in a file
  413. because it lists the sources that have been locally modified.
  414. It is best to save the file in a different directory (for example,
  415. your home directory). Otherwise,
  416. .B checkin
  417. will try to check it into the master repository.
  418. .TP
  419. \(bu
  420. In your usual working directory, check out a fresh copy of the
  421. distribution that you just checked in.
  422. .XS
  423. cd ~/work
  424. cvs checkout \-r VENDOR bugs
  425. .XE
  426. The
  427. .B checkout
  428. command shown above retrieves the latest revision on the vendor branch.
  429. .TP
  430. \(bu
  431. See the `WARNINGS' file for a list of all locally modified
  432. sources.
  433. For each locally modified source,
  434. look at the differences between
  435. the new distribution and the latest local revision:
  436. .XS
  437. cvs diff \-r \fR\fILocalRev file\fR\fB
  438. .XE
  439. In this command,
  440. .I LocalRev
  441. is the latest
  442. numeric or symbolic revision
  443. on the RCS trunk of
  444. .IR file .
  445. You can use CVS
  446. .B log
  447. to get the revision history.
  448. .TP
  449. \(bu
  450. If your local modifications to a file have been incorporated into
  451. the vendor's distribution, then you should reset the default RCS
  452. branch for that file to the vendor branch. CVS doesn't provide a
  453. mechanism to do this. You have to do it by hand in the master
  454. repository:
  455. .XS
  456. rcs \-bVENDOR \fR\fIfile\fR\fB,v
  457. .XE
  458. .TP
  459. \(bu
  460. If your local modifications need to be merged with the
  461. new distribution, use CVS
  462. .B join
  463. to do it:
  464. .XS
  465. cvs join \-r VENDOR \fR\fIfile\fR\fB
  466. .XE
  467. The resulting file will be placed in your working directory.
  468. Edit it to resolve any overlaps.
  469. .TP
  470. \(bu
  471. Test the merged package.
  472. .TP
  473. \(bu
  474. Commit all modified files to the repository:
  475. .XS
  476. cvs commit \-a
  477. .XE
  478. .TP
  479. \(bu
  480. Tag the repository with a new local tag.
  481. .SS "Applying Patches to Third-Party Sources"
  482. Patches are handled in a manner very similar to complete
  483. third-party distributions. This example considers patches applied to
  484. Bugs-R-Us release 5.0.
  485. .TP
  486. \(bu
  487. Save the patch files together with the distribution kit
  488. to which they apply.
  489. The patch file names should clearly indicate the patch
  490. level.
  491. .TP
  492. \(bu
  493. In a scratch directory, check out the last `clean' vendor copy \- the
  494. highest revision on the vendor branch with
  495. .IR "no local changes" :
  496. .XS
  497. cd ~/scratch
  498. cvs checkout \-r VENDOR bugs
  499. .XE
  500. .TP
  501. \(bu
  502. Use
  503. .BR patch (local)
  504. to apply the patches. You should now have an image of the
  505. vendor's software just as though you had received a complete,
  506. new release.
  507. .TP
  508. \(bu
  509. Proceed with the steps described for merging a subsequent third-party
  510. distribution.
  511. .TP
  512. \(bu
  513. Note: When you get to the step that requires you
  514. to check out the new distribution after you have
  515. checked it into the vendor branch, you should move to a different
  516. directory. Do not attempt to
  517. .B checkout
  518. files in the directory in
  519. which you applied the patches. If you do, CVS will try to merge the
  520. changes that you made during patching with the version being checked
  521. out and things will get very confusing. Instead,
  522. go to a different directory (like your working directory) and
  523. check out the files there.
  524. .SS "Advice to Third-Party Source Hackers"
  525. As you can see from the preceding sections, merging local changes
  526. into third-party distributions remains difficult, and probably
  527. always will. This fact suggests some guidelines:
  528. .TP
  529. \(bu
  530. Minimize local changes.
  531. .I Never
  532. make stylistic changes.
  533. Change makefiles only as much as needed for installation. Avoid
  534. overhauling anything. Pray that the vendor does the same.
  535. .TP
  536. \(bu
  537. Avoid renaming files or moving them around.
  538. .TP
  539. \(bu
  540. Put independent, locally written files like help documents, local
  541. tools, or man pages in a sub-directory called `local-additions'.
  542. Locally written files that are linked into an existing executable
  543. should be added right in with the vendor's sources (not in a
  544. `local-additions' directory).
  545. If, in the future,
  546. the vendor distributes something
  547. equivalent to your locally written files
  548. you can CVS
  549. .B remove
  550. the files from the `local-additions' directory at that time.
  551. .SH SEE ALSO
  552. .BR cvs (local),
  553. .BR checkin (local),
  554. .BR cvslog (local),
  555. .BR cvscheck (local)
  556. .SH AUTHOR
  557. Lowell Skoog
  558. .br
  559. Software Technology Group
  560. .br
  561. Technical Computing