< Zurück | Inhalt | Weiter >

8.2.6 Log

With each cvs commit you are prompted for a comment, to describe the changes that you are committing. What happens to these comments? How can you see them again? Use the cvs log command to show the history of a file’s revisions and associated comments.

See Example 8.2 for an example of the cvs output command. Looking down the output of cvs log, you can see

• The complete filename—in the repository—of the file whose log we’re checking out.

• The local filename in your sandbox.

• Which revision is the “head,” that is, the front-most or default revision.

• Which branch, if any.

• What kind of locking mechanism CVS uses. There are some choices, but most users of CVS leave this as is.

• The access limitations. CVS can limit who can modify files (see our reference list if you need to use this).

• A list of all the tags (symbolic names) for this module and to which revision each refers.

• What kind of keyword substitution happens. For binary files this would be kb.

• The count of revisions for this file.

Then comes a description of each of the revisions, showing

• The revision number.

• Some stats on the change including the user ID of the user who committed the change.

• How many lines were added and deleted compared to the previous revi- sion.


image

Example 8.2 An example of running the cvs log command

$ cvs log Account.java

RCS file: /usr/local/srcbank/JavaAppDevLinux/Account.java,v Working file: Account.java

head: 1.4 branch: locks: strict access list:

symbolic names:

keyword substitution: kv

total revisions: 4; selected revisions: 4 description:

----------------------------

revision 1.4

date: 2003/05/20 11:59:59; author: albing; state: Exp; lines: +80 -5 more comments added

----------------------------

revision 1.3

date: 2003/05/18 15:03:23; author: albing; state: Exp; lines: +3 -2 end case fixed

----------------------------

revision 1.2

date: 2003/05/17 11:05:40; author: albing; state: Exp; lines: +69 -2 actually runs - unit tested

----------------------------

revision 1.1

date: 2003/05/17 10:15:18; author: albing; state: Exp; a rough structure

=======================================================================


image


• The comment that was entered when the user committed the change.

(For a description of state, and why you will almost always see Exp;, see the Cederqvist reference in Section 8.6.)

Do you want less output from cvs log? You can restrict the information to cover only a certain user’s changes (-w), to a certain range of revisions (-r), and/or between certain dates (-d).

For example,


cvs -walbing -r1.2:1.4 -d05-Sep03 -d28-Sep-03 Account.java


will list only changes committed by user albing, only in the revision range of

1.2 through 1.4, and only between the dates of 05 and 28 September of 2003.


Note: do not put a space between the -w, -r, or -d and its parameter or CVS will think that the parameter is the name of a source module, and you will see a message like this:


$ cvs log -r 1.2:1.4 Account.java cvs log: nothing known about 1.2:1.4

...


which will be followed by output about the Account.java module that CVS does know about.

For more variations on the logging output, type:


$ cvs log --help


8.2.7 cvs status

While the cvs log command will tell you about the history of all revisions of a file, you sometimes need to know the status of the current file in your sand- box: Which revision is it? From where did it come? And, most importantly, is it part of the head or part of a branch?

Those questions can be answered with the cvs status command. Its output will show the revision number of the file in your sandbox and any “sticky” tags. But to understand what that means, we need to talk about tags first.


8.2.8 cvs tag

We began this chapter asking: “Can you find or create a set of sources that matches exactly what your customer is running? Can you then provide a mod- ified version that contains only the fix necessary and no other changes?” Part of the answers to these questions will depend on your use of the cvs tag command. With it, you can set down a label across all your source to mark a particular milestone, so that later you can recall that version of the source. For example,


$ cvs tag Rel_2_4


will put a tag (that is, a label) called Rel_2_4 on the head revision of all source files from the directory where this command was executed on down through


all its subdirectories. If you run this command from the uppermost directory in your project sandbox, it will label your entire project.

image

A tag can be applied to a single file or group of files by listing them explicitly on the command line.



NOTE

Certain special characters are not allowed in CVS tags. Specifically, the charac- ters $,.:;@ are not allowed. So you can’t use release_2.4 as a tag. Too bad.


Tags cut across the various revisions of the source. While you can specify that a tag goes on the same revision of all sources (e.g., cvs tag -r 1.3 one_dot_three_tag), the more typical use is to tag different revisions of each module, the revisions that you’ve just been working with and testing.

Figure 8.3 shows a tag (QA) that cuts across the various revisions of the different sources. With such a tag, someone can check out a copy of the sources to get the QA release:


$ cvs co -r QA project




a.java v. 1.1


a.java v. 1.2


a.java v. 1.3








b.java v. 1.1


b.java v. 1.2


b.java v. 1.3


b.java v. 1.4





c.java v. 1.1


c.java v. 1.2



image

image

QA tag


Figure 8.3 A tag across three files


Since your project would likely have more than one time in its life that it would be handed off to QA, some people will put date information in the tag, for example, QA_2003_07_15. Others will use a simple tag, such as QA, but such a tag may need to be reused.

If you’ve put down a tag and decide that you no longer want that tag (for example, your product is preparing for a new QA cycle and you want to reuse last cycle’s tag, or maybe you simply misspelled your tag), you can delete it using the -d option.



WARNING

Once you delete a tag, it’s gone forever. It is not available even when you recall earlier versions. If you reuse a deleted tag, it doesn’t remember any history from its first use.

image


Imagine your project has just reached a milestone, like the hand-off to QA, so you have tagged your source accordingly. Now the QA group finds a bug and you fix it. What do you do with the tag? The tag will be on the unfixed version of source. One thing that you can do, after you commit your changes, is simply to move the label:


$ cvs commit Account.java

...

$ cvs tag -F QA Account.java


This will “force” the tag on Account.java to move to the current version.

Such a mechanism works fine for the short term, for quick changes that are put in shortly after the tag has been set down. But what if it takes QA several days to find the bug, and what if, during that time, you’ve been refactoring Account.java, or adding features for a future release? In those cases, what you really need is a branching tag.