CVS Multi-developer environment

1. 數位芝麻網路公司 蔡志展 <chihchun@digitalsesame.com> 2001/8/18 CVS Multi-developer environment

2. The CVSROOT/ Administrative Directory • The files in newrepos/CVSROOT/ are not part of any project, but are used to control CVS's behavior in the repository. The best way to edit those files is to check out a working copy of CVSROOT, just like a regular project:

3. The CVSROOT/ Administrative Directory $ cvs co CVSROOT cvs checkout: Updating CVSROOT U CVSROOT/checkoutlist U CVSROOT/commitinfo U CVSROOT/config U CVSROOT/cvswrappers U CVSROOT/editinfo U CVSROOT/loginfo U CVSROOT/modules U CVSROOT/notify U CVSROOT/rcsinfo U CVSROOT/taginfo U CVSROOT/verifymsg

4. The CVSROOT/ Administrative Directory • We'll take the files in their approximate order of importance. Note that each of the files comes with an explanatory comment at the beginning (the comment convention is the same across all of them: A # sign at the beginning of the line signifies a comment, and CVS ignores such lines when parsing the files). Remember that any change you make to the administrative files in your checked out working copy won't affect CVS's behavior until you commit the changes.

5. The CVSROOT/ Administrative Directory • If you're extremely security conscious, you may want to arrange the Unix-level permissions on CVSROOT to be different from permissions elsewhere in the repository, in order to have fine-grained control over who can commit changes to CVSROOT. As you'll see a little later, being able to modify the files in CVSROOT essentially gives any CVS user - even remote ones - the ability to run arbitrary commands on the repository machine.

6. CVSROOT/Administrative files • The config File: • The modules File: • The commitinfo And loginfo And rcsinfo Files: • The verifymsg And rcsinfo Files: • The taginfo File: • The cvswrappers File: • The notify File: • The checkoutlist File:

7. The Config file • The config file allows you to configure certain global behavioral parameters.

8. The Config file # Set this to "no" if pserver shouldn't check system users/passwords #SystemAuth=no # Set `PreservePermissions' to `yes' to save file status information # in the repository. #PreservePermissions=no # Set `TopLevelAdmin' to `yes' to create a CVS directory at the top # level of the new working directory when using the `cvs checkout' # command. #TopLevelAdmin=no

9. The Module File • In modules, you can define aliases and alternate groupings for projects in the repository. The most basic module line is of the form: MODULE_NAME DIRECTORY_IN_REPOSITORY

10. The Module File For Example: mp myproj $ cvs co mp cvs checkout: Updating mp U mp/README.txt U mp/foo.jpg U mp/hello.c

11. The commitinfo And loginfo And rcsinfo • Most of the other administrative files provide programmatic hooks into various parts of the commit process (for example, the ability to validate log messages or file states before permitting the commit, or the ability to notify a group of developers whenever a commit happens in a certain directory of the repository).

12. The commitinfo And loginfo And rcsinfo • The files generally share a common syntax. Each line is of the form: REGULAR_EXPRESSION PROGRAM_TO_RUN

13. The commitinfo And loginfo And rcsinfo • The regular expression will be tested against the directory into which the commit is taking place (with the directory name relative to the top of the repository). If it matches, the designated program will be run. The program will be passed the names of each of the files in the commit; it can do whatever it likes with those names, including opening up the files and examining their contents. If the program returns with a nonzero exit status, the commit is prevented from taking place

14. The commitinfo file The commitinfo file is for generic hooks you want run on every commit. Here are some example commitinfo lines: /usr/local/bin/check-asubdir.sh ou /usr/local/bin/validate-project.pl

15. The loginfo file • The loginfo file is similar to commitinfo, except that instead of acting on the files' contents, it acts on the log message. The left side of the loginfo file contains regular expressions, including possibly DEFAULT and ALL lines. The program invoked on the right side receives the log message on its standard input; it can do whatever it wants with that input.

16. The loginfo file • The program on the right side can also take an arbitrary number of command-line arguments. One of those arguments can be a special % code, to be expanded by CVS at runtime, as follows: %s ------> name(s) of the file(s) being committed %V ------> revision number(s) before the commit %v ------> revision number(s) after the commit

17. The loginfo file • a sample loginfo file: ou /usr/local/bin/ou-notify.pl %{sv} DEFAULT /usr/local/bin/default-notify.pl %{sVv}

18. The verifymsg And rcsinfo Files • Sometimes you may just want a program to automatically verify that the log message conforms to a certain standard and to stop the commit if that standard is not met. This can be accomplished by using verifymsg, possibly with some help from rcsinfo.

19. The taginfo File • What loginfo does for log messages, taginfo does for tags. The left side of taginfo is regular expressions, as usual, and the right side is programs.

20. The taginfo File • Each program is automatically handed arguments when CVS tag is invoked, in this order:

21. The cvswrappers File • The redundantly-named cvswrappers file gives you a way to specify that certain files should be treated as binary, based on their file name. CVS does not assume that all .jpg files are JPG image data, for example, so it doesn't automatically use -kb when adding JPG files. Nonetheless, certain projects would find it very useful to simply designate all JPG files as binary. Here is a line in cvswrappers to do that: *.jpg -k 'b'

22. The cvswrappers File • The b is separate and in quotes because it's not the only possible RCS keyword expansion mode; one could also specify o, which means not to expand $ sign keywords but to do newline conversion. However, b is the most common parameter. • There are a few other modes that can be specified from the wrappers file, but they're for such rare situations that they're probably not worth documenting here (translation: your author has never had to use them). See the node Wrappers in the Cederqvist if you're curious.

23. The checkoutlist File • CVS only pays attention to the working versions, not the RCS files, when it's looking for guidance on how to behave. Therefore, whenever you commit your working copy of CVSROOT/ (which might, after all, even be checked out to a different machine), CVS automatically updates any changed files in the repository itself.

24. Watches (CVS As Telephone) • A major benefit of using CVS on a project is that it can function as a communications device as well as a record-keeper. This section concentrates on how CVS can be used to keep participants informed about what's going on in a project. As is true with other aspects of CVS, these features reward cooperation. The participants must want to be informed; if people choose not to use the communications features, there's nothing CVS can do about it.

25. How Watches Work • In its default behavior, CVS treats each working copy as an isolated sandbox. No one knows what you're doing in your working copy until you commit your changes. In turn, you don't know what others are doing in theirs - except via the usual methods of communication, such as shouting down the hallway, "Hey, I'm going to work on parse.c now. Let me know if you're editing it so we can avoid conflicts!"

26. How Watches Work • This informality works for projects where people have a general idea of who's responsible for what. However, this process can break down when a large number of developers are active in all parts of a code base and want to avoid conflicts. In such cases, they frequently have to cross each others' areas of responsibility but can't shout down the hallway at each other because they're geographically distributed.

27. How Watches Work • A feature of CVS called watches provides developers with a way to notify each other about who is working on what files at a given time. By "setting a watch" on a file, a developer can have CVS notify her if anyone else starts to work on that file. The notifications are normally sent via email, although it is possible to set up other notification methods.

28. How Watches Work • To use watches, you must modify one or two files in the repository administrative area, and developers must add some extra steps to the usual checkout/update/commit cycle. The changes on the repository side are fairly simple: You may need to edit the CVSROOT/notify file so that CVS knows how notifications are to be performed. You may also have to add lines to the CVSROOT/users file, which supplies external email addresses.

29. How Watches Work • On the working copy side, developers have to tell CVS which files they want to watch so that CVS can send them notifications when someone else starts editing those files. They also need to tell CVS when they start or stop editing a file, so CVS can send out notifications to others who may be watching. The following commands are used to implement these extra steps: • cvs watch • cvs edit • cvs unedit

30. Enabling Watches In The Repository • First, the CVSROOT/notify file must be edited to turn on email notification. One of the developers can do this, or the repository administrator can if the developers don't have permission to change the repository's administrative files.

31. Enabling Watches In The Repository • Editing the notify file in this way may be all that you'll need to do for watches in the repository. However, if there are remote developers working on the project, you may need to edit the CVSROOT/users file, too. The purpose of the users file is to tell CVS where to send email notifications for those users who have external email addresses. The format of each line in the users file is:

32. Enabling Watches In The Repository • Editing the notify file in this way may be all that you'll need to do for watches in the repository. However, if there are remote developers working on the project, you may need to edit the CVSROOT/users file, too. The purpose of the users file is to tell CVS where to send email notifications for those users who have external email addresses. The format of each line in the users file is: CVS_USERNAME:EMAIL_ADDRESS

33. Using Watches In Development • cvs watch add hello.c, tells CVS to notify jrandom if anyone else starts working on hello.c (that is, it adds jrandom to hello.c's watch list). For CVS to send notifications as soon as a file is being edited, the user who is editing it has to announce the fact by running cvs edit on the file first. CVS has no other way of knowing when someone starts working on a file.

34. Changing A Log Message After Commit • Just in case someone does commit a regrettable log message, CVS enables you to rewrite logs after they've been committed. It's done with the -m option to the admin command (this command is covered in more detail later in this chapter) and allows you to change one log message (per revision, per file) at a time.

35. Changing A Log Message After Commit • Here's how it works: cvs admin -m 1.7:"Truncate four-digit years to two in input." date.c

36. Annotations - A Detailed View Of Project Activity • The annotate Command

37. Using Keyword Expansion • RCS keywords are special words, surrounded by dollar signs, that CVS looks for in text files and expands into revision-control information.

38. Keyword • For example, if a file contains • $Author$ • $Author: chihchun $

39. Here are a few other commonly used keywords: $Author$ $Date$ ==> date of last commit $Id$ ==> filename, revision, date, and author $Revision$ ==> exactly what you think it is $Source$ ==> path to corresponding repository file $Log$ ==> accumulating log messages for the file

40. CVSWeb http://sources.redhat.com/cgi-bin/cvsweb.cgi/

41. Thank You !! Q&A