The word 'checkout'[1] in CVS refers to downloading the files to your local machine. It is analogous to you checking out a book from the library, however you are not only expected to bring it back, but update it too!
$ cvs checkout projects
|
The above command will create a directory structure on your computer, which will have everything that is under projects on the CVS repository. So, let us say we don't want everything under projects. Let us assume that you want the bicon project source and everything for it.
$ cvs checkout projects/bicon
|
When you 'commit' a file, you are essentially uploading it to the repository. So, now that you have downloaded the files and have made some changes, you would like to put it back on the repository.
For the sake of this example, we will say you are modifying the file 'myfile.cc'. Here is how to commit it:
$ cvs commit myfile.cc
|
If the file does not already exist, and you are creating a new one then you need to 'add' it first. Here is how:
$ cvs add myfile.cc $ cvs commit myfile.cc |
The first command creates an entry for the file in the repository, and the second one actually makes the commit to the repository (making it available). If the file already exists and you are making changes to it, you can ignore the 'cvs add' command. For more help do 'man cvs' from your linux/unix prompt.
Once you execute the commit command, a text editor will be launched so you can enter a brief log of what you have done. This is especially useful for others who are working on the same project - as it gives them an insight of what you have changed without having to look through the file(s). The editor is usually vi, on most Linux/Unix systems.However, that is not necessarily the case. It is whatever you have the environment $EDITOR set to. To find out what it is set to in your environment, do:
$ env | grep EDITOR
|
In order to get into insert mode under VI, press i. Then you may continue to type in your brief log. Once you are done, press ESC (which will get you out of the insert mode), and enter :wq then hit return. This will write (to save) and quit. Your commit will then be executed.
When you have made changes that span across multiple files it is best to commit them in one batch, as opposed to doing so one at a time. That is for 2 main reasons:
Minimizes on the amount of cvs notification mail that goes out to everyone on the 'cvs' list, whenever a commit is made.
Most of the time the multiple files changed involve the same issue. For example, if the two files test.cc and test.h were changed, it is unnecessary to commit them individually.
There are two ways of committing multiple files.
$ cvs commit file1 file2 file3
|
Or you can simply let it recursively do it:
$ cvs commit
|
The first gives you more flexibility in what the files are exactly, whereas the latter simply commits any file that has changed in the current directory and all subdirectories.
New directories are either created as part of an existing project or to create a new module for a newly imported project. Before creating any new directory, please always consult the CVS administrator. This is particularily important to avoid redundancy and maintain an ordered organization.
This does not apply to those who are module owners. For instance, if the author of X decided to add X/yz/ to his X/ directory, it does not require any approval from the CVS administrator.
Although this does not happen very often, it is worth noting here, especially for those who own a project and would like to add a new directory with some content in it already.
When that is the case, use cvs import. For example, if projX in projects/projX is about to add a new directory called games with 10 files in it, do this:
$ cvs import projects/projX/games arabeyes start
|
For more information type cvs import --help' or consult the CVS Manual.
It goes without saying that it is very important to enter a useful and meaningful comment on commits.
Translation (PO's):
When committing .po file(s) always make sure the comment includes the output of:
$ msgfmt --statistics file.po [2] |
This is to avoid commit logs such as "translated a little", which mean very little if anything at all.
Development Source Code:
Comments on source code commits may be a little easier (as the types of changes will vary). Always make sure you keep track of the changes you make AS you make them, so you remember what they are before committing.
An example of a bad log is: "I made a few fixes". What fixes? If you can't remember what you did anymore, then do a diff of the changes, go through it and note the changes you made.
Documents:
Generally documentation comments are inevitably going to be vague. If the document is small, that's not a problem. If it is not, point to the location you made the changes to. For example: "Chapter 3, Section 4 - Re-wrote the second paragraph for clarity" is a good comment.
There is a very simple rule to follow on this one. Any file that is generated by a program from another file that resides on CVS should not be put on CVS. That is unnecessary redundancy.
Compressed files (gzip/bzip2/Z/etc) should not be put on CVS in their compressed/tarred forms.
Generally the only binary type of files acceptable on CVS are graphics images and audio files. Every other file type is expected to be text.
Since there are others who are likely to have made changes during the course of the project, your local working copy of the cvs contents may not always be up to date. In order for you to keep your copy up-to-date you can:
$ cvs update
|
Note that this can only be done while you are inside the directory you are intending to update.