[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

12. Version Control System

12.1 The VCS Explorer  
12.2 The VCS Menu  
12.3 The Version Control Contextual Menu  
12.4 Working with global ChangeLog file  

GPS offers the possibility for multiple developers to work on the same project, through the integration of version control systems (VCS). Each project can be associated to a VCS, through the VCS tab in the Project property editor. See section 7.7 The Project Properties Editor.

GPS does not come with any version control system: it will use an underlying command-line system such as CVS or ClearCase to perform the low level operations, and provides a high level user iterface on top of them. Be sure to have a properly installed version control system before enabling it under GPS.

The systems that are supported out of the box in GPS are CVS and ClearCase. There are two interfaces to ClearCase: the standard ClearCase interface, which is built-in and uses a generic GPS terminology for VCS operations, and the Native ClearCase interface, which is fully customizable and uses by default the terminology specific to ClearCase.

Note that, at the moment, only Snapshot Views are supported in the ClearCase integration; Dynamic Views are not supported.

It is also possible to add your own support for other version control systems, or modify the existing CVS and ClearCase interfaces, see 15.8 Adding support for new Version Control Systems for more information.

When using CVS, GPS will also need a corresponding patch command that usually comes with it. If you are under Windows, be sure to install a set of CVS and patch executables that are compatible.

It is recommended that you first get familiar with the version control system that you intend to use in GPS first, since many concepts used in GPS assume basic knowledge of the underlying system.

Associating a VCS to a project enables the use of basic VCS features on the source files contained in the project. Those basic features typically include the checking in and out of files, the querying of file status, file revision history, comparison between various revisions, and so on.

Administration of VCS systems is not handled by GPS at this stage. Therefore, before working on a project using version control system, make sure that the system is properly set-up before launching GPS.

Note: the set-up must make sure that the VCS commands can be launched without entering a password.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

12.1 The VCS Explorer

The VCS Explorer provides an overview of source files and their status.

vcs-explorer

The easiest way to bring up the VCS Explorer is through the menu VCS->Explorer. The Explorer can also be brought up using the contextual menu Version Control->Query status on files, directories and projects in the file and project views, and on file editors. See section 12.3 The Version Control Contextual Menu.

The VCS Explorer contains the following columns:

Status
Shows the status of the file. This column can be sorted by clicking on the header. The different possible status for files are the following:

Unknown
gps-vcs-unknown
The status is not yet determined or the VCS repository is not able to give this information (for example if it is unavailable, or locked).

Not registered
gps-vcs-not-registered
The file is not known to the VCS repository.

Up-to-date
gps-vcs-up-to-date
The file corresponds to the latest version in the corresponding branch on the repository.

Added
gps-vcs-added
The file has been added remotely but is not yet updated in the local view.

Removed
gps-vcs-removed
The file still exists locally but is known to have been removed from the VCS repository.

Modified
gps-vcs-modified
The file has been modified by the user or has been explicitly opened for editing.

Needs merge
gps-vcs-needs-merge
The file has been modified locally and on the repository.

Needs update
gps-vcs-needs-update
The file has been modified in the repository but not locally.

Contains merge conflicts
gps-vcs-has-conflicts
The file contains conflicts from a previous update operation.

Log
This column indicates whether a revision log exists for this file.

File
The name of the file. This column can be sorted by clicking on the header.

Working rev.
Indicates the version of the local file.

Head rev.
Indicates the most recent version of the file in the repository.

The VCS Explorer supports multiple selections. To select a single line, simply left-click on it. To select a range of lines, select the first line in the range, then hold down the Shift key and select the last line in the range. To add or remove single columns from the selection, hold down the Control key and left-click on the columns that you want to select/unselect.

The explorer also provides an interactive search capability allowing you to quickly look for a given file name. The default key to start an interactive search is Ctrl-i. See Interactive Search for more details.

The VCS contextual menu can be brought up from the VCS explorer by left-clicking on a selection or on a single line. See section 12.3 The Version Control Contextual Menu.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

12.2 The VCS Menu

Basic VCS operations can be accessed through the VCS menu. Most of these functions act on the current selection, i.e. on the selected items in the VCS Explorer if it is present, or on the currently selected file editor, or on the currently selected item in the Project/File View. In most cases, the VCS contextual menu offers more control on VCS operations. See section 12.3 The Version Control Contextual Menu.

Explorer
Open or raise the VCS Explorer. See section 12.1 The VCS Explorer.

Update all projects
Update the source files in the current project, and all imported sub-projects, recursively.

Query status for all projects
Query the status of all files in the project and all imported sub-projects.

For a description of the other entries in the VCS menu, see 12.3 The Version Control Contextual Menu


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

12.3 The Version Control Contextual Menu

This section describes the version control contextual menu displayed when you right-click on an entity (e.g. a file, a directory, a project) from various parts of GPS, including the project explorer, the source editor and the VCS Explorer.

Depending on the context, some of the items described in this section won't be shown, which means that they are not relevant to the current context.

Query status
Query the status of the selected item. Brings up the VCS Explorer.

Update
Update the currently selected item (file, directory or project).

Commit
Submits the changes made to the file to the repository, and queries the status for the file once the change is made.

It is possible to tell GPS to check the file before the actual commit happens. This is done by specifying a File checker in the VCS tab of the project properties dialog. This File checker is in fact a script or executable that takes an absolute file name as argument, and displays any error message on the standard output. The VCS commit operation will actually occur only if nothing was written on the standard output.

It is also possible to check the change-log of a file before commit, by specifying a Log checker in the project properties dialog. This works on change-log files in the same way as the File checker works on source files.

Open
Open the currently selected file for writing. On some VCS systems, this is a necessary operation, and on other systems it is not.

View entire revision history
Show the revision logs for all previous revisions of this file.

View specific revision history
Show the revision logs for one previous revision of this file.

Compare against head revision
Show a visual comparison between the local file and the most recent version of that file in the repository.

Compare against other revision
Show a visual comparison between the local file and one specific version of that file in the repository.

Compare between two revisions
Show a visual comparison between two specific revisions of the file in the repository.

Compare base against head
Show a visual comparison between the corresponding version of the file in the repository and the most recent version of that file.

Annotate
Display the annotations for the file, i.e. the information for each line of the file showing the revision corresponding to that file, and additional information depending on the VCS system.

When using CVS, the annotations are clickable. Left-clicking on an annotation line will query and display the changelog associated to the specific revision for this line.

Remove Annotate
Remove the annotations from the selected file.

Edit revision log
Edit the current revision log for the selected file.

Edit global ChangeLog
Edit the global ChangeLog entry for the selected file. see section 12.4 Working with global ChangeLog file.

Remove revision log
Clear the current revision associated to the selected file.

Add
Add a file to the repository, using the current revision log for this file. If no revision log exists, activating this menu will create one.

Remove
Remove a file from the repository, using the current revision log for this file. If no revision log exists, activating this menu will create one.

Revert
Revert a locale file to the repository revision, discarding all local changes.

Directory
Only available when the current context contains directory information

Query status for directory
Query status for the files contained in the selected directory.

Update directory
Update the files in the selected directory.

Query status for directory recursively
Query status for the files in the selected directory and all subdirectories recursively, links not included.

Update directory recursively
Update the files in the selected directory and all subdirectories recursively, links not included..

Project
Only available when the current context contains project information

List all files in project
Brings up the VCS Explorer with all the source files contained in the project.

Query status for project
Queries the status for all the source files contained in the project.

Update project
Updates all the source files in the project.

List all files in project and sub-projects
Brings up the VCS Explorer with all the source files contained in the project and all imported sub-projects.

Query status for project and sub-projects
Queries the status for all the source files contained in the project and all imported sub-projects.

Update project and sub-projects
Updates all the source files in the project and all imported sub-projects.

Hide up-to-date files
Only available from the VCS Explorer. Filter out up-to-date files, that is files that have not been modified locally and that do not need to be updated.

Hide non registered files
Only available from the VCS Explorer. Filter out non registered files, that is files unknown to the version control system, or whose information could not be retrieved (e.g. the version control server is temporarily unavailable).


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

12.4 Working with global ChangeLog file

A global ChangeLog file contains revision logs for all files in a directory and is named `ChangeLog'. The format for such a file is:

 
   ISO-DATE  name  <e-mail>

   <HT>* filename[, filename]:
   <HT>revision history

where:

ISO-DATE
A date with the ISO format YYYY-MM-DD

name
A name, generally the developer name

<e-mail>
The e-mail address of the developer surrounded with '<' and '>' characters.

HT
Horizontal tabulation (or 8 spaces)

The name and <e-mail> items can be entered automatically by setting the GPS_CHANGELOG_USER environment variable. Note that there is two spaces between the name and the <e-mail>.

 
On sh shell:

   export GPS_CHANGELOG_USER="John Doe  "

On Windows shell:
   set GPS_CHANGELOG_USER="John Doe  "

Using the menu entry Edit global ChangeLog will open the file `ChangeLog' in the directory where the current selected file is and create the corresponding `ChangeLog' entry. This means that the ISO date and filename headers will be created if not yet present. You will have to enter your name and e-mail address.

This `ChangeLog' file serve as a repository for revision logs, when ready to check-in a file use the standard Edit revision log menu command. This will open the standard revision log buffer with the content filled from the global `ChangeLog' file.


[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

This document was generated by Mail Server on November, 29 2004 using texi2html