CVS Workshop - University of Manitoba · CVS –the Concurrent Versioning System, is a version control system generally used as part of the software development cycle to track and

2005-10-21 Gary F. Alderson - University of Manitoba

1

CVS Workshop

How to manage your projects, source code, and associated files using the Concurrent Versioning System


2

Purpose

� CVS is the most commonly used Open Source Version Management System.

� We need to backup, maintain and manage the objects used to develop projects as well as the ability to track changes through past versions.

� We need to have a consistently implemented multi-platform source repository for all source for each system.


3

Key Definitions

� CVS – the Concurrent Versioning System, is a version control system generally used as part of the software development cycle to track and co-ordinate source code changes among a team of developers.

� Project – A collection of programs, scripts, data files, documentation, and other associated objects which together address a single function or subsystem as defined by the Project Team. They must decide on the granularity.

� Module – Often confused with Project, but in CVS terms, a commonly defined object used by multiple Projects.

� Sandbox - CVS has a unique method of working from most other version control systems in that developers can edit the same files concurrently. This is done by checking out a version of the project from the repository into a local directory on your computer. This local copy is called a sandbox.


4

MVS vs UNIX Environments“The Life of a Modification”

MVS/IMS Environment

1. userid.ee123.project()

2. Restore source� userid.ee123.cobol� userid.ee123.cntl� userid.load(ee123)

3. a0011.dp.t901d(ee123)

4. imsvs.temppgm(ee123)

5. imsvs.pgmlib(ee123)

6. Backup source to PDP008

7. Delete userid.ee123.cobol

UNIX/Web Environment

1. $HOME/sandbox/ee123/

2. cvs checkout ee123� ee123.c� ee123.test.sh� ee123 (executable)

3. /priv/adminsys/wwwdevl/htdocs/webapp/ee/ee_app/ee123

4. /priv/adminsys/wwwpromote/htdocs/webapp/ee/ee_app/ee123

5. /priv/adminsys/wwwprod/htdocs/webapp/ee/ee_app/ee123

6. cvs commit

7. cvs release -d ee123


5

Using CVS in the UNIX Environment


6

CVS – Creating a Project

� As an example, let's create a new project consisting of a shell script and a Perl script that announce themselves to the world.

� You first need to create a directory to hold all of the files required for the project. One idea is to have a directory called “newproject” inside your sandbox directory.

� Create the two files ee_hello_world and ee_hello_world.pl in the directory. A quick way to do this is to copy the two example files from /priv/adminsys/courses/introduction-to-unix/sample-files.

� Edit and modify the files to add your own personal information.

� To avoid clobbering your neighbour, rename the scripts to ee_xxx_hello_world where xxx is your userid.

� Note the CVS “keywords” $Id, $Source, $Log. CVS will manage these provided you enter them in a comment area.


7

CVS - Importing a Project

� Now that you have your files ready, you can import your project into the CVS repository.

� Note there can be as many repositories as we require. At this point, we define one per System ID. For this course however, you must use the course repository. You must set the environment variable CVSROOT=”/priv/adminsys/courses/introduction-to-unix/cvs” and export it via export CVSROOT.

� Inside the your “newproject” directory, you can now issue the cvs import command: “cvs import ee_xxx_hello_world V R” again xxx is your userid. V and R are used by import for release names.

� Provided you did not get any error messages, your project files are now entered into the CVS repository. You can now delete the files in your “newproject” directory.


8

CVS - Import Example<alders@chara:218>$ pwd

/home/u1/alders/sandbox/newproject

<alders@chara:219>$ ls -l

total 16

-rwxrwx--- 1 alders adpcat 1028 Jul 2 11:17 ee_alders_hello_world

-rwxrwx--- 1 alders adpcat 583 Jul 2 11:17 ee_alders_hello_world.pl

<alders@chara:220>$ CVSROOT="/priv/adminsys/courses/introduction-to-unix/cvs"

<alders@chara:221>$ export CVSROOT

<alders@chara:222>$ cvs import ee_alders_hello_world V R

(You will be asked to enter comments about the changes made.

Enter them and save)

N ee_alders_hello_world/ee_alders_hello_world

N ee_alders_hello_world/ee_alders_hello_world.pl

No conflicts created by this import


9

CVS - Checking Out a Project

� You are now ready to checkout the project from the repository to make changes and work on it. This is done via “cvs checkout”

� Change your directory to your ~/sandbox and then run the command “cvs checkout ee_$USER_hello_world”

� Note the directory ~/sandbox/ee_xxx_hello_worldhas been created and it will contain two files that you previously imported.

� Edit the files and see what CVS has done the the CVS comments.

� You can now make any changes required, test your changes, etc.


10

CVS - Checkout Example

<alders@chara:247>$ cd ~/sandbox

<alders@chara:248>$ pwd

/home/u1/alders/sandbox

<alders@chara:249>$ echo $CVSROOT

/priv/adminsys/courses/introduction-to-unix/cvs

<alders@chara:250>$ cvs checkout ee_alders_hello_world

cvs checkout: Updating ee_alders_hello_world

U ee_alders_hello_world/ee_alders_hello_world

U ee_alders_hello_world/ee_alders_hello_world.pl

<alders@chara:251>$ ls -l ee_alders_hello_world

total 24

drwxrws--- 2 alders adpcat 4096 Jul 2 13:23 CVS

-rwxrwxr-x 1 alders adpcat 1279 Jul 2 13:07 ee_alders_hello_world

-rwxrwxr-x 1 alders adpcat 843 Jul 2 13:07 ee_alders_hello_world.pl


11

CVS - Committing Changes

� Once you have finished making changes to the project and have tested them, you are ready to commit your changes to the repository

� In our example, edit the two files to make some minor changes. Test them to make sure you are happy that the changes work.

� Ensure that you are located in the project sandbox directory.

� Ensure that CVSROOT points to the correct repository.� Run “cvs commit” to commit your changes.� Note, if you have a one-line change comment that is

common to all of your files, you can specify this using the “-m” command line option. Be sure to enclose the text in “ “.


12

CVS - Commit Example

<alders@chara:281>$ echo $CVSROOT/priv/adminsys/courses/introduction-to-unix/cvs<alders@chara:282>$ pwd/home/u1/alders/sandbox/ee_alders_hello_world

<alders@chara:283>$ cvs commit -m "Make production ready"cvs commit: Examining .Checking in ee_alders_hello_world;/priv/adminsys/courses/introduction-to-

unix/cvs/ee_alders_hello_world/ee_alders_hello_world,v <--ee_alders_hello_world

new revision: 1.2; previous revision: 1.1doneChecking in ee_alders_hello_world.pl;/priv/adminsys/courses/introduction-to-

unix/cvs/ee_alders_hello_world/ee_alders_hello_world.pl,v<-- ee_alders_hello_world.pl

new revision: 1.2; previous revision: 1.1done


13

CVS - Add/Remove Files

� Throughout the life of a project, other files will need to be added to the repository such as test data, test scripts, documentation, etc.

� These are added to the project using the “cvs add” command.� To add a file or directory, locate to the project directory where

the file or directory already exists and run “cvs add file1 file2 ...”

� Conversely, over time files will no longer be required and can be deleted from the project. This is done with “cvs remove”.

� You must first delete the files or directories physically and then run the command: “cvs remove file1 file2 ...”

� CVS will schedule addition or removal of file on the next commit.

� Note, files that are removed are actually stored away in the project's “attic” in case they are ever needed again.


14

CVS - Add/Remove Example<alders:286>$ cvs add ee_alders_hello_world.txt \

ee_alders_hello_world.20040702.150217.logcvs add: scheduling file èe_alders_hello_world.txt' for additioncvs add: scheduling file èe_alders_hello_world.20040702.150217.log' for

additioncvs add: use 'cvs commit' to add these files permanently<alders:287>$ rm ee_alders_hello_world.20040702.150217.logrm: remove ee_alders_hello_world.20040702.150217.log (yes/no)? y<alders:288>$ cvs remove ee_alders_hello_world.20040702.150217.logcvs remove: removed èe_alders_hello_world.20040702.150217.log'<alders:289>$ cvs commit -m “Add documentation files to project”cvs commit: Examining .RCS file: /priv/adminsys/courses/introduction-to-

unix/cvs/ee_alders_hello_world/ee_alders_hello_world.txt,vdoneChecking in ee_alders_hello_world.txt;/priv/adminsys/courses/introduction-to-

unix/cvs/ee_alders_hello_world/ee_alders_hello_world.txt,v <--ee_alders_hello_world.txt

initial revision: 1.1done


15

CVS - Project Deployment

� In today's environment of primarily scripting language, it is tempting to change the component's source where it is run from. It is essential that all changes done to a project's components be done inside the CVS sandbox directories. In order to manage the changes, CVS needs to know that the source code it has is the only set being changed.

� To ease this synchronization, CVS has an export command, which will export only the project files into a named directory. This does not export the CVS internal files. It can also deploy only a specific release or released date.

� To run the command for the most current release committed, execute “cvs export -d targetdirectory -D now projectname”


16

CVS - Export Example<alders@chara:314>$ cvs export -D now \-d /home/adpc/cservap/ee/app/ee_alders_hello_world \ee_alders_hello_worldcvs export: Updating /home/adpc/cservap/ee/app/ee_alders_hello_worldU /home/adpc/cservap/ee/app/ee_alders_hello_world/ee_alders_hello_worldU /home/adpc/cservap/ee/app/ee_alders_hello_world/ee_alders_hello_world.plU /home/adpc/cservap/ee/app/ee_alders_hello_world/ee_alders_hello_world.txt

<alders@chara:315>$ ls -l \/home/adpc/cservap/ee/app/ee_alders_hello_worldtotal 24-rwxrwxr-x 1 alders cservap 1362 Jul 2 15:13 ee_alders_hello_world-rwxrwxr-x 1 alders cservap 933 Jul 2 15:13 ee_alders_hello_world.pl-rw-rw-r-- 1 alders cservap 497 Jul 2 15:31 ee_alders_hello_world.txt


17

CVS - Cleaning Up

� Of course once you have committed all of your changes and are satisfied that everything is working correctly in production, you should clean up your sandbox.

� This is not mandatory, but always a best practice to make sure that you do not exceed your disk space quota, as well as to make sure that you have closed your checkout and have freed up any locks.

� Make sure to position yourself to your ~/sandboxdirectory, ie. One level above the project.

� Run the command “cvs release -d projectname”� This will delete the files and directories belonging to

the project and remove your userid from checkout status in the repository.


18

CVS - Release Example<alders@chara:303>$ lsafauthentication ee_alders_hello_worlddc_generate_parms ee_perl_examplesdc_job hr_umfadd_operational_documentation hr_vipdaemonsdp_check_cronlog newprojectdp_errorlog ordp_rotate rsvalpindp_services xxx

<alders@chara:304>$ pwd/home/u1/alders/sandbox

<alders@chara:305>$ cvs release -d ee_alders_hello_worldYou have [0] altered files in this repository.Are you sure you want to release (and delete) directory

èe_alders_hello_world': y

<alders@chara:306>$ ls -ld ee_alders_hello_worldee_alders_hello_world: No such file or directory


19

CVS - Beyond Simple Projects

� CVS is the most commonly used source management tool in the industry. It is commonly used to manage open source projects with developers working on joint projects world-wide.

� CVS can define “modules” which are made up of components from different projects. Hence a module can share and reuse components across many projects. Further research needs to be done locally to establish best practices on how we accomplish this. Stay tuned.

� CVS will become the basis to production change control and change management of projects being promoted into various environments, such as production and training.

� Admin Systems will move System based CVS repositories on to a remote CVS server to provide better access and security from all platforms. EG. Windows, UNIX, Linux, MacIntosh, Web, etc.


20

CVS - Best Practices

� We are still gaining experience with CVS. It is a very powerful product with many options. Expect a great many best practices to come in the near future as people gain experience with it.

� The discipline of making changes only to project components within a CVS sandbox and then exporting the changes into executable directories is critical to success. Only use “cvs export” or “cp” project files into their executable environments. Never make changes to components in these directories directly.

� CVS is not a substitute for good project management. Project leads need to actively ensure that project staff get assigned to projects where overlapping work is avoided or controlled. CVS will attempt to resolve concurrent changes to project files, however, good definition and granularity decisions for the projects is critical.


21

Using CVS in the Windows Environment

Using TortoiseCVS


22

Checking out a Module

� Using Windows Explorer, right-click on C:\Sandbox and select CVS Checkout:

� Protocol should be set to Password server [:pserver:]

� Server should be set to chara.cc.umanitoba.ca

� Repository folder: to your system’s repository

� User name: your userid� Module if you know it or

press Fetch list to populate the pulldown.

� Click OK to Checkout the Project.


23

Creating a Project

� To create a new project, create a folder under C:\Sandbox using the name of the project. In this case I used ee_course_test

� Right click on the new folder and select “CVS”then “Make New Module …”


24

CVS - Add/Remove Example

� After you have created the project files in the new project directory, right click on the directory name and select “CVS Add Contents …”

� The file icons will change to show they are now a part of the project.


25

Adding/Removing Files Later

� To remove or add files individually, select the file by clicking on it and then right click the file and select either “CVS Add…” or “CVS” then “-Remove” and click OK.

� Notice that the file icon will change to reflect its new status.


26

Committing the Project

� When you are ready to commit your project into the repository, right click on the project’s directory icon and select “CVS Commit …”

� Enter comments explaining the changes you may have done and click OK.


27

Cleaning Up

� After you have committed your project, you should now cleanup your sandbox. To do this, right click on the project directory and select “CVS” then “Release…”

� You can now click ok and the directory will be deleted. Note if any files were not added to the project, the directory will remain with those files in it and you will then need to manually delete them.


28

Using CVS in the Web Environment

Using CVSWEB


29

Selecting Repositories and Projects

� By selecting Application Technologies from the pulldown, and then selecting ee_course_test, you can now view the project we had entered in the above examples.


30

Accessing CVSWEB

� We have installed a CVS web repository viewer known as CVSWEB.

� http://pasweb.cc.umanitoba.ca/webapp/at/cvsweb

� If any new repositories are created, inform Application Technologies to set them up

� Security is setup based on ip address and userid/password control. Userids need to be added by Application Technologies.


31

Viewing Project Objects

� Individual Objects in each projects can be viewed in a number of ways.

� Shown here is the historical summary

� The following slides will shown the various detailed views.


32

Viewing Object as Text

� By selecting the “Text” view you will be presented with a simple ASCII text page showing the source code of the object.


33

Viewing Object as Markup

� By selecting the “Markup” view you will be presented with a header containing summary information followed by a text page showing the source code of the object.


34

Viewing Object as Annoted

� By selecting the “Annoted” view you will be presented with a text page showing the source code of the object. In the left margin there are indicators showing in which revision changes occurred.


35

Viewing Object as “Select for Diffs”

� By selecting the “Select for Diffs” view you will first be presented with a seclection page to choose which version to compare.

� Next by selecting “Preferred” you will be presented with a colourcoded page showing the source code of the object. The left side will be the previous selected version and the right the newer version.


36

References

� There are several documents found in S:\Adminsys\DOCS\CVS.

� The official site for CVS can be found at http://ximbiot.com/cvs/wiki

� TortoiseCVS has an excellent on-line help file. There are portion still under construction however.

� Also see http://www.tortoisecvs.org

CVS Workshop - University of Manitoba · CVS –the Concurrent Versioning System, is a version control system generally used as part of the software development cycle to track and

Documents