Getting Started W ith CVS An Oracle White Paper February 2005 Getting Started W ith CVS Introduction....................................................................................................... 3 W HAT IS CVS.................................................................................................. 3 terminology........................................................................................................ 3 CVS Step by step............................................................................................... 4 Downloading and Installing CVS............................................................... 4 Creating a Repository................................................................................... 5 Creating a CVS Connection........................................................................ 5 Configuring the Repository......................................................................... 6 Importing a Module...................................................................................... 7 Checking Out a Module............................................................................... 9 Adding Files................................................................................................... 9 Updating Files (Common)......................................................................... 10 Editing Files................................................................................................. 11 Deleting Files............................................................................................... 11 Committing Files......................................................................................... 12 Comparing Files.......................................................................................... 13 Merging Files............................................................................................... 14 Renaming Files............................................................................................ 14 View Revisions............................................................................................ 14 Tagging Files................................................................................................ 15 Updating Files (Special)............................................................................. 15 Retrieving Deleted Files............................................................................. 16 OTHER CVS CLIENTS............................................................................... 16 TortoiseCVS................................................................................................ 16 W inCVS........................................................................................................ 17 SUBVERSION: THE BETTER CVS......................................................... 18 More Information............................................................................................ 18 White Paper Title Page 2 Getting Started W ith CVS INTRODUCTION Are you in need of a tool that supports a structured way of sharing sources between developers? Or do you want to have the ability to exactly know what files you changed at some point in time, and perhaps be able to revert changes you have made? Than read on and find out how CVS can help you out and find out how CVS integrates with JDeveloper 10.1.2. WHAT IS CVS CVS stands for Concurrent Versions System and is a so-called version control system. A version control system is used to keep several versions of a set of files, typically source code, in a repository. The files kept in the repository can be shared between developers, allowing them to see who is editing what files, what changes have been made by who, when and why that happened. You can revert to a previous version when necessary. The repository can reside anywhere on the network, which might be your local computer. So you can use a local, private repository when there is no need to share it with other developers. TERMINOLOGY The CVS repository can contain one or more modules. A module basically is a folder structure, typically containing all (source code) files of one specific project. To create a module, the folder structure and the files in it need to be uploaded from the file system into the repository. This upload (that is the creation of a module) is called an import. From the moment a file has been uploaded into the repository, it is said it has been put “under version control”. Before you can work with a module locally, you need to retrieve it from the repository by doing a checkout. Unlike some other version control systems, checking out a module with CVS has nothing to do with locking or flagging files as being edited, as will be explained later. White Paper Title Page 3 The software you use to import or checkout a module is called a CVS client. The CVS client can either be some stand-alone program or being integrated with your IDE, as is the case with JDeveloper. W hen checking out a module some extra files are created that are used by the CVS client, to determine what files are new and what files have been edited. Before you can upload a new file into the repository, you need to add it. Adding a file is like registering it for the module it belongs to. Once you finished your work, you can upload modified and new files (that have been added first) by doing a commit. In case of a modified file, this results in a new version or revision of that file. CVS will keep a history of all revisions, allowing you to revert to some previous version. You can retrieve other developers’ new or modified files from the repository by doing an update. If someone else has changed the file in the repository, CVS can automatically merge your changes during the update. W hile updating a file you can get a clean copy, which will undo any changes you have made. You can provide files with a tag, which is a label. Tagging is typically used to label a release of a module. CVS STEP BY STEP The following will guide you through the options of CVS that you as a developer will use most often. In order to be able to practice most options on your own computer, the first step is to download CVS and create a repository. Downloading and Installing CVS The core of CVS is the CVS engine, which is available for both Unix and W indows. Next to JDeveloper, this paper will discuss two popular CVS clients being TortoiseCVS and W inCVS, that both can act as a standalone CVS “engine” (the upcoming JDeveloper 10.1.3 will also be able to act as a standalone engine, but as this document is based on JDeveloper 10.1.2 that will not be discussed). In the remainder of this paper, TortoiseCVS or W inCVS is used to provide a standalone CVS engine, while JDeveloper is discussed as being the CVS client. At some point it is discussed how TortoiseCVS and W inCVS as a CVS client can add to JDeveloper. A few specifically useful features of TortoiseCVS and W inCVS are highlighted at the end of this paper. You can download TortoiseCVS from http://www.tortoisecvs.org and W inCVS from http://www.wincvs.org. For the remainder of this document it is assumed that you downloaded one of these clients and that you create a local, standalone repository. In case you need a shared repository CVSNT is recommended, which can be downloaded from http://www.cvsnt.com). After installing the CVS client, make sure the folder that contains cvs.exe is in your path (for example C:\Program Files\GNU\W inCVS 1.3\CVSNT or C:\Program Files\Tortoise). White Paper Title Page 4 Creating a Repository In the remainder of the paper an example is used of a JDeveloper workspace called CVSTryouts that resides in the folder J:\demos\CVSTryouts. The workspace has three projects in it: McyAnalysis, McyModel and McyView. Suppose you want to store these projects in a repository called CVSTryouts. W e will then work to a situation as in the following figure, where the local project is at the left side and the repository at the right site. The “remote” repository can reside anywhere on the network, including the same computer on which the local project folder structure resides. In this example does the local project reside on J-drive while the repository will reside on the D-drive. First you need to create a folder that will contain your CVS repository, for example D:\CVS. Open a command prompt box and check the path by executing the following command: cvs -version Keep the command prompt box open. You can now create the repository itself, by executing the following command in a command prompt window: cvs –d D:\CVS\CVSTryouts init The init command created a new folder D:\CVS\CVSTryouts, with a CVSROOT subfolder. This CVS root has been specified by the -d option and should refer to the absolute path of the repository to create. The CVSROOT folder is the “index” of the repository. The contents of the repository should not be modified by hand. Creating a CVS Connection Before you can use CVS from JDeveloper, you need to configure JDeveloper to use CVS. You need to have the cvs.exe in your path first, as has been described in “Downloading and Installing CVS”. You can now configure JDeveloper to use CVS by going to Tools -> Preferences -> Extension M anager -> Version Control and choose CVS. The CVS client has now been integrated with JDeveloper. White Paper Title Page 5 The next step is to create a CVS connection to your repository. You do this by opening the Connections Navigator, right-click on the CVS Server node and choose New CVS Connection. This