Source Code Control (Komodo Pro)

"Source code control" refers to the practice of storing files containing program source code (and other project artifacts) in a common repository. Using source code control (SCC), multiple developers can work on the same project (including the same project file) at the same time. The SCC repository can be queried for a detailed listing of the changes that occurred each time a file was edited. Files under source code control that are open for editing can also be reverted to their previous state.

Komodo's SCC integration works in conjunction with the CVS, Subversion and Perforce source code control systems.

Depots, repositories, branches, and projects cannot be created or configured from within Komodo. This must be done using the SCC software itself. Komodo's SCC features become available when files are checked out from the source code repository.

From within Komodo, you can perform the following SCC actions:

  • add files to the repository
  • remove files from the repository
  • compare files in the editor against their repository versions (a "diff")
  • show a revision history for a file
  • submit files back to the repository
  • revert files to their previous state

Additionally, files under Perforce control are recognized by Komodo even when they are not open for edit. They can be opened via the File menu, SCC context menus (locations described below), or the SCC toolbar.

Komodo is intended to work in conjunction with these SCC programs; it does not replace them. TortoiseCVS and TortoiseSVN are useful tools for managing files under source code control from within Windows Explorer. Perforce provides P4Win, a graphical client for Windows used to view and manage files in a SCC repository.

Komodo SCC functions are accessible from the following locations:

  • Toolbox Context Menu: Right-click a file in the Toolbox to access the Source Control menu options. Source code control functions can also be performed on Folders in the Toolbox; right-click a folder and select Source Control on Contents to access the menu.
  • Project Manager context menu: Right-click a file in the Project Manager to access the Source Control menu options. SCC functions can also be performed on Folders in the Toolbox; right-click a folder and select Source Control on Contents to access the menu. Two source code control options are available from the Project Manager and Toolbox context menus:
    • Source Control applies source code functions to the selected file only.
    • Source Control on Contents applies source code functions to the contents of the selected project or folder.
  • Editor Pane: Right-click a file in the Editor Pane to access the Source Control menu options.
  • Filename Tab: Right-click the filename tab above the Editor Pane to access the Source Control menu options.
  • File Menu: Select the Source Control option from the File menu.

The Source Control submenu options are the same regardless of which method is used to access the menu.

Using Source Code Control

SCC Toolbar, Menus and Output Tab

Source Code Control Toolbar

Access common source code control commands from the SCC Toolbar at the top of the Komodo workspace. Refer to the command descriptions below for more information. The toolbar commands only apply to the file currently active in the Editor Pane.

 

Source Code Control Menus

To access source code control functions, select File|Source Control.

Invoke source code control context menus by right-clicking files or folders in the following areas:

 

Source Code Control Output Tab and Status Messages

The SCC Output tab is located in the Bottom Pane of the Komodo workspace. As you execute source code control commands, such as editing or checking in files, details of the commands are displayed on the SCC Output tab.

Error messages and warnings are also displayed on the SCC Output tab. Additionally, error messages and warnings are displayed on the status bar in the bottom left corner of the Komodo workspace.

 

Source Code Control Commands

As described above, source code control commands are invoked from the toolbar, the File menu and the Source Control context menu. The following commands are available, depending on the context:

  • Add: Add a file from a designated source code directory on your local drive to the source code repository.
  • Edit: Check out a file from the current source code repository.
  • Revert Changes: Check the file back into the repository, abandoning any changes made since it was checked out.
  • Remove: Delete the file from both the source code repository and the corresponding local directory.
  • Update: When the local version no longer matches the repository version of a file, select this command to update the local version of the file.
  • Diff (Compare Files): Compare the version of a file open in the Editor Pane with the version in the source code repository. Depending on the setting in Preferences, the diff display is shown on another Komodo editor tab or in a separate window. If the display style for diffs (Edit|Preferences|Source Code Control) is set to Create new window, press 'F9' or select Jump to Corresponding Line to open and/or shift focus to the original file in the Editor Pane. If viewing a diff in an editor tab, right-click and select Jump to Corresponding Line to shift focus to the editor tab containing the source code. Selecting this option opens the source code tab in the Editor Pane if it is not already open.
  • History: Show the change history for the current file.
  • Commit Changes: Submit the file back to the source code repository.

Under Perforce, to open files for edit from within a Komodo project, you must first add files to the project using options on the Project menu. To accomplish the same under CVS, use the following procedure:

  1. At the command prompt, enter cvs co <projname> to open working copies of the files.
  2. On the Projects tab, right-click the project and select Import from File System.
  3. In the Import from File System dialog box, specify the location of the files to be imported and click Next.
  4. Click OK to confirm changes to the project.

 

File Status Icons

If Perforce, CVS or Subversion is enabled in Komodo's Preferences, the status of files in the source code repository is indicated by icons that appear on file tabs in the Editor Pane and next to files and projects on the Projects tab.

The icons can appear in a variety of combinations, depending on the status of the file and where they are displayed in the Komodo workspace. For example, a green circle next to a padlock on a tab in the Editor Pane indicates that the file is open for edit and that the version of the file in your local directory is in sync with the version in the source code repository.

The file is being added to the source code repository.
The file is being deleted from the source code repository.
The file is open for edit.
The version of the file in your local directory is in sync with the version in the source code repository.
The file is read-only.
The version of the file in your local directory is out of sync with the version in the source code repository.
There is a conflict between the version of the file in your local directory and the source file that cannot be resolved by simply syncing your directory with the source code repository. The discrepancy must be manually resolved.

Refresh Status

To refresh the SCC status of the current file do one of the following:

  • Right-click the on file tab or within the editor pane and select Refresh Status
  • Right-click on the file in the Project tab and select Refresh Status
  • Click Refresh Status on the File menu
  • Press 'Ctrl' + 'K', 'R'

To refresh the SCC status of an entire folder, do one of the following:

  • Right-click the on the folder and select Refresh Status
  • Select the folder in the Project tab and click Refresh Status on the File menu
  • Select the folder in the Project tab and press 'Ctrl' + 'K', 'R'

 

Configuring Source Code Control Integration

Configuring CVS

Installing the CVS Executable

To view the location of the CVS executable files found on your system and to determine which executable is used, select Edit|Preferences|Source Code Control|CVS. If CVS is not properly configured, or if the CVS executable file you have is incompatible with Komodo, the CVS Source Code Control page in Komodo Preferences displays a message advising that CVS integration is disabled. To begin configuring CVS, click Download CVS and follow the instructions on the ASPN web site.

The CVS executable must be located in a directory specified in your system's PATH environment variable, or you will need to configure the path to the executable in Komodo's preferences.

On Windows 98 and Me, you must configure a HOME environment variable, for example "HOME=c:\". Reboot before proceeding.

 

CVS Over SSH

Some CVS repositories (e.g. SourceForge) will only support CVS access over SSH (secure shell). When accessing these repositories, an SSH client is required. See Configuring SSH Support for CVS and Subversion below for details on configuring SSH support.

 

Configuring Subversion

Installing the Subversion Executable

To view the location of the Subversion executable files found on your system and to determine which executable is used, select Edit|Preferences|Source Code Control|Subversion. If Subversion is not properly configured, the Subversion Source Code Control page in Komodo Preferences displays a message advising that Subversion integration is disabled. To begin configuring Subversion, click Download Subversion and follow the instructions on the ASPN website.

The Subversion executable must be located in a directory specified in your system's PATH environment variable, or you will need to configure the path to the executable in Komodo's preferences.

Komodo will only contact the Subversion server when Refresh Status is clicked for the a file or folder

 

Subversion Over SSH

Some Subversion repositories only support Subversion access over SSH (secure shell). When accessing these repositories, an SSH client is required. See Configuring SSH Support for CVS and Subversion below for details on configuring SSH support.

 

Configuring Perforce

Ensure that the command-line version of Perforce ("P4") is correctly installed and functional before working with a Perforce repository within Komodo. The p4.exe file must be located in a directory that is specified in your PATH environment variable.

Users of Perforce's P4CONFIG feature may find that Komodo's source code control doesn't work unless Komodo is started from within the client view of the Perforce repository.

 

Configuring Preferences

Use the Source Code Control page in Komodo's Preferences to configure Source Code Control integration. To open the Komodo Preferences dialog box, select Edit|Preferences.

 

Configuring SSH Support for CVS and Subversion

Tunneling your CVS or Subversion connections over SSH can provide an added level of security for your repository access. CVS and Subversion use very similar methods for tunneling over an SSH connection. On Windows, download and install Putty or Cygwin to provide SSH support. Linux and OS X distributions typically include SSH support.

This is a basic guideline for configuring CVS and Subversion to use SSH, however, because server configurations can vary, you should consult the documentation for the control system you are using, or request help from you system administrator.

The use of Pageant (on Windows) or ssh-agent (OS X and Linux) with Komodo is strongly recommended.

Installing and Configuring Putty on Windows

Putty is a free SSH, Telnet and Rlogin client for Windows.

1. Install Putty

Download Putty (version 0.52 or greater) and associated programs from:

http://www.chiark.greenend.org.uk/~sgtatham/putty/

To connect to a server via SSH, the following programs are required:

  • putty.exe
  • puttygen.exe
  • pageant.exe
  • pscp.exe
  • plink.exe

Ensure that the directory where Putty is installed is specified in your system's PATH environment variable.

2. Generate the Putty Key

Run the puttygen utility. Configure as follows:

  1. Set Parameters: Select either "SSH2 RSA" or "SSH2 DSA".
  2. Generate Key Pair: Click the Generate button to generate the key pair. While the key is being generated, move the mouse pointer around the blank space to provide key randomness.
  3. Enter Key Passphrase: Enter and confirm a passphrase for the key. Remember the passphrase - it is required later.
  4. Save Public Key: Click the "Save public key" button and store the key in a file called public1.key.
  5. Save Private Key: Click the Save private key button and store the key in a file called private1.key, in the same directory as the public key.
    Note: The extension .ppk will be appended to the name specified (i.e. private1.key.ppk).
  6. Copy Key Contents: Copy the contents of the public key field (at the top of the dialog box) to a file named public1-openssh.key. This key is required later.
  7. Close puttygen

3. Load and Configure the Putty Authentication Agent

Run the pageant program. This loads the Putty Authentication Agent into the Windows System Tray.

Right-click the Pageant icon in the Windows System Tray. Select Add Key. Navigate to the directory where you saved the public and private keys in the previous step, and select the file private1.key.ppk.

4. Configure Putty To Use Pageant

Run the putty program. Configure as follows:

  1. Specify Server: On the Session page of the Configuration form, enter the host name or IP address of the server.
  2. Specify Protocol: On the Session page, in the Protocol field, select the "SSH" protocol.
  3. Create Saved Session: In the Saved Sessions field, enter the host name again. Click the Save button.
  4. Configure Connection: on the Connection page of the Configuration form, enter your username for the server in the Auto-login username field.
  5. Configure SSH Protocol: On the SSH page of the Configuration form, specify "2" for the Preferred SSH protocol version.
  6. Enable Agent Forwarding: On the Auth page of the Configuration form, check Allow agent forwarding. In the Private key file for authentication field, specify the path and filename of the private key created above (private1.key).
  7. Save Session Information: On the Session page of the Configuration form, click the Save button.

5. Store the Public Key on the Server

You must store the public key file generated in step 2 (public1-openssh.key) on the CVS or Subversion server.

  1. Open Command Prompt Window: Type cmd in the Windows Run dialog box.
  2. Copy Public Key to Server: At the command prompt, enter: 
    pscp c:\path\to\public1-openssh.key username@server.com:public1-openssh.key

    ...where c:\path\to\public1-openssh.key specifies the location of the key file created in step two, and username@server.com specifies your username and URL on the remote server. You are prompted to confirm the legitimacy of the host, and may be prompted to enter your password for the server.

  3. Connect Using Putty: If necessary, run the putty program. In the Saved Sessions field, double-click the configuration created in Step 4. This establishes a connection to the server.
  4. Configure the Key on the Server: After logging on to the server, enter the following commands to configure the SSH key: 
        mkdir ~/.ssh
    chmod 700 .ssh
    cat ~/public1-openssh.key >> ~/.ssh/authorized_keys
    rm ~/public1-openssh.key
    chmod 600 ~/.ssh/*
  5. Log Off and Exit Putty: Enter exit to close the session of the server.

6. Test the Configuration

Restart Putty. In the Saved Sessions field, double-click the configuration created in Step 4. You should not be prompted to log in. If you are, the configuration failed. Review the steps above and ensure that they were completed correctly.

Using CVS with Putty on Windows

Use the following additional steps if you are using CVS with Komodo.

7. Check Out a CVS Module

  1. Create Local CVS Directory: Create a directory to store a copy of the CVS repository.
  2. Copy Files to Local Directory: At a command prompt, enter: 
        set CVS_RSH=plink
    set PLINK_PROTOCOL=ssh
    cvs -d :ext:username@cvs.server.com:/repository_name co cvs_module

    ...where username@cvs.server.com specifies your username on the CVS server and the URL of the CVS server, repository_name specifies the name of the repository on the server, and cvs_module specifies the name of the module in the chosen working repository.

    Login is handled by SSH. The files are copied to the local system. These environment variables do not interfere with non-SSH repositories.

Ensure that these variables are permanently configured in your system environment (for example, by adding them to the autoexec.bat file or configuring them in the system properties). Reboot Windows Me and 9x systems after adding environment variables.

8. Using Komodo and CVS

Before starting Komodo, perform the following steps:

  • Set PLINK_PROTOCOL=ssh: In the user environment, set the environment variable PLINK_PROTOCOL to "ssh".
  • Set CVS_RSH=plink: In the user environment, set the environment variable CVS_RSH to "plink".
  • (Windows 9x and Me only)Set HOME=C:\: On Windows 98 and Windows Me, configure the HOME environment variable in the autoexec.bat file.
  • Ensure Pageant Is Running: Run the pageant program to enable the authentication agent. Ensure that the private1.key is loaded.

    You can also execute Pageant and load the key via a batch file. For example:

        C:\PuTTY\pageant.exe c:\path\to\private.key c:\path\to\private2.key

If you are running Windows 9x or Windows Me, permanently configure these variables in the environment (for example, by adding them to the autoexec.bat file) and reboot before proceeding.

 

Using Subversion with Putty on Windows

Use the following additional steps if you are using Subversion with Komodo.

7. Check Out a Subversion Repository

  1. Create Local Subversion Directory: Create a directory to store a copy of the Subversion repository.
  2. Copy Files to Local Directory: At a command prompt, enter: 
        svn checkout svn+ssh://svn.server.com/repository_path/module/ local_path

    ...where svn.server.com specifies the server domain name of the Subversion server, repository_path/module specifies the path of the repository on the server, and local_path specifies the preferred location on your local system for your copy of the repository. The local_path can be ommited, in which case the local path is the last part of the repository_path.

    Login is handled by SSH. The files are copied to the local system.

Ensure that these variables are permanently configured in your system environment (for example, by adding them to the autoexec.bat file or configuring them in the system properties). Reboot Windows Me and 9x systems after adding environment variables.

8. Using Komodo and Subversion

Before starting Komodo, perform the following steps:

  • Set PLINK_PROTOCOL=ssh: In the user environment, set the environment variable PLINK_PROTOCOL to "ssh".
  • Set SVN_SSH=c:/path/to/plink.exe: In the user environment, set the environment variable SVN_SSH to the full path to "plink.exe". (use forward slashes instead of back slashes in the path, or it will not work.)

    NOTE: You can use the local Subversion configuration file instead of setting the environment variable. This permits configuration of different connection types. The config file is located in the Subversion directory, typically inside the Application Data area of the user's profile directory (eg. C:\Documents and Settings\USERNAME\ Application Data\Subversion). See the Subversion documentation for more information.

    	Subversion Config File:

        [tunnels]
        ssh = $SVN_SSH plink.exe

    If you use "plink = $SVN_SSH plink.exe" in the tunnels section of the config file, then use svn+plink as the scheme in your checkout url rather than svn+ssh.

  • (Windows 9x and Me only)Set HOME=C:\: On Windows 98 and Windows Me, configure the HOME environment variable in the autoexec.bat file.
  • Ensure Pageant Is Running: Run the pageant program to enable the authentication agent. Ensure that the private1.key is loaded.

    You can also execute Pageant and load the key via a batch file. For example:

        C:\PuTTY\pageant.exe c:\path\to\private.key c:\path\to\private2.key

If you are running Windows 9x or Windows Me, permanently configure these variables in the environment (for example, by adding them to the autoexec.bat file) and reboot before proceeding.

 

Configuring CVS with Windows/Cygwin-SSH or Linux/SSH

To configure CVS to use SSH, refer to http://xml.apache.org/forrest/community/howto/cvs-ssh/howto-cvs-ssh.html.

On all platforms, create an environment variable as follows:

    CVS_RSH=ssh

CVS determines when to use SSH, depending on how you check out the modules. If you use the "cvs login" method with the "pserver" protocol, CVS does not use SSH, even if CVS_RSH=ssh is set in the environment.

On Windows, also configure the cygwin SSH Agent as follows:

  1. Open a cygwin shell.
  2. Enter exec ssh-agent bash.
  3. Enter ssh-add.
  4. To check out a CVS module, enter: 
        cvs -d :ext:username@cvs.server.com:/repository_name co cvs_module

    ...where username@cvs.server.com specifies your username on the CVS server and the URL of the CVS server, repository_name specifies the name of the repository on the server, and cvs_module specifies the name of the module in the chosen working repository.

  5. Start Komodo within the cygwin shell as follows: 
        /path/to/komodo/komodo.exe

After completing the configuration steps above, follow these steps to open Komodo with CVS-SSH enabled:

  1. Open a cygwin shell.
  2. Enter exec ssh-agent bash.
  3. Enter ssh-add.
  4. Start Komodo within the cygwin shell as follows: 
    /path/to/komodo/komodo.exe

 

Configuring Subversion with Windows/Cygwin-SSH or Linux/SSH

To configure Subversion to use SSH, refer to http://svnbook.red-bean.com/en/1.0/index.html.

Subversion determines when to use SSH, depending on how you check out the modules. If you use an HTTP or FILE URI, Subversion will not use SSH. Subversion configurations are very customizable and may not exactly match the examples below.

On Windows, configure the Cygwin SSH Agent as follows:

  1. Open a cygwin shell.
  2. Enter exec ssh-agent bash.
  3. Enter ssh-add.
  4. To check out a Subversion module, enter: 
        svn checkout svn+ssh://svn.server.com/repository_path/module/ local_path

    ...where svn.server.com specifies the server domain name of the Subversion server, repository_path/module specifies the path of the repository on the server, and local_path specifies the preffered location on your local system for your copy of the repository. The local_path can be ommited, in which case the local path is the last part of the repository_path.

  5. Start Komodo within the cygwin shell as follows: 
        /path/to/komodo/komodo.exe

After completing the configuration steps above, follow these steps to open Komodo with Subversion-SSH enabled:

  1. Open a cygwin shell.
  2. Enter exec ssh-agent bash.
  3. Enter ssh-add.
  4. Start Komodo within the cygwin shell as follows: 
    /path/to/komodo/komodo.exe