IntelliJ IDEA Integration

From Seapine Labs

Contents 1 Background 2 Installing the IntelliJ IDEA Plug-In 3 Sharing projects 4 Basic Surround SCM tasks 4.1 Adding files 4.2 Getting files 4.3 Checking out files 4.4 Undoing check out 4.5 Checking in files 4.6 Viewing file history 4.7 Viewing file properties 4.8 Viewing File Differences 4.9 Viewing Repository Differences 4.10 Renaming files 4.11 Refreshing file status 4.12 Removing files 4.13 Disconnecting a project 5 Advanced Surround SCM tasks 5.1 Configuring Surround SCM preferences 6 Troubleshooting IntelliJ IDEA and Surround SCM integration

[edit] Background

This article was written using Surround SCM 5.0.4 and IntelliJ IDEA (Windows) version 5.1.2.

Also, it is assumed that the IntelliJ IDEA project has never been under source control, none of the files in this project have been added to Surround SCM and that the directory where the project resides is not associated as a working directory in Surround SCM.

[edit] Installing the IntelliJ IDEA Plug-In

The IntelliJ IDEA plug-in is installed during the Surround SCM installation.

NOTE: Stop IntelliJ IDEA before you install the plug-in.

1. Run the Surround SCM installation program.

2. You will be prompted to select Surround SCM Integration options.

3. Select Install IntelliJ IDEA plug-in.

4. Select the correct option for the version of IntelliJ IDEA you are using.

5. Browse to select the IntelliJ IDEA installation directory to install the plug-in.

You are now ready to begin using IntelliJ IDEA with Surround SCM.

[edit] Sharing projects

First, you need to associate the IntelliJ IDEA project with Surround SCM.

1. Open the IntelliJ IDEA project.

When the project opens, the following prompt should appear:

Since the directory where the project resides is not associated with a repository, a prompt appears indicating this.

3. Click on "Fix" to associate the project being opened with Surround SCM.

4. Click on "Ignore" to not associate the current project but get this prompt again when you open another project.

5. Click on "Ignore All" to not associate any project while this instance of IntelliJ IDEA is open.

Since we want to associate the project that is being open, we click on "Fix".

This opens the Branch Repository Browser Window.

You must either select an existing repository or click on the "Create Repository" button to create a new one. If you select an existing repository, its working directory must be the directory where the project resides. Otherwise, the integration will not work. Selecting an existing repository will not automatically change the working directory, this must be done manually by right clicking on the repository and selecting "Set Working Directory...".

Creating a new repository will automatically assign the project directory as the working directory for the new repository.

Figure below shows the Branch Repository Browser Window with the "Set Working Directory..." menu from a repository's context menu. It should be noted that if a new repository is created one MUST use the context menu and set the working directory of an existing repository to the folder where the project resides.

After you create a new repository, it may not be selected by default. Make sure that the correct repository is selected before you click OK to close the Branch Repository Browser Window.

6. Click OK.

You are now logged in and ready to start using Surround SCM. Start with the Basic Surround SCM tasks if the project and its files currently exist in Surround SCM.

[edit] Basic Surround SCM tasks

Please refer to the Surround SCM User Guide for details on all of the options given for all of the Surround SCM tasks.

[edit] Adding files

NOTE: You must add files individually to Surround SCM. There is no package support in the add operation which would allow you to add a group of files like in other IDEs (like Eclipse and WebSphere). You can, however, select multiple files and add them at the same time.

1. Select the file(s) you want to add to source control.

2. Right-click and choose "Surround SCM" > "Add".

The Advanced Add Options dialog box opens.

Please refer to the Surround SCM User Guide for details on all of the options given in the Advanced Add Options dialog box.

3. Click OK.

The files are added to Surround SCM.

[edit] Getting files

Get files when you want to view a file but do not need to make any changes.

1. Select the file(s) you want to get.

2. Right-click and choose and choose Surround SCM > Get.

The Advanced Get Options dialog box opens.

Note: You can also select a project, right click and choose Surround SCM > Pull Project to get a copy of all files in the project.

Please refer to the Surround SCM User Guide for details on all of the options given in Advanced Get Options dialog box.

3. Click OK to get the file(s).

Surround SCM copies the files into the working directory.

[edit] Checking out files

Check out files when you want to modify them.

1. Select the file(s) you want to check out.

2. Right-click and choose Surround SCM > Check Out.

The Advanced Check Out Options dialog box opens.

Please refer to the Surround SCM User Guide for details on all of the options given for the Advanced Check Out Options dialog box.

3. Click OK.

The files are checked out.

[edit] Undoing check out

If you check out and modify a file, then decide you do not want to save the changes, you can undo the check out. This discards any changes made to the file and checks it back into the server.

1. Select the file(s).

2. Right-click and choose Surround SCM > Undo Check Out.

The Advanced Undo Check Out Options dialog box opens.

3. Click OK.

The file is no longer checked out.

[edit] Checking in files

Check in updates the file with changes and makes it available to other users.

1. Select the file(s) you want to check in.

2. Right-click and choose Surround SCM > Check In.

The Advanced Check in Options dialog box opens.

3. Click OK.

The files are checked in.

[edit] Viewing file history

File history provides a way to view a source file’s history and work with a historical file version.

1. Select the file.

2. Right-click and choose Surround SCM > History.

The History dialog box opens. This dialog box includes a summary of historic version information. You can view historic information and Diff or Get versions of the file.

3. Click Close to close the file history.

[edit] Viewing file properties

You can view Surround SCM file properties from within IntelliJ IDEA.

1. Select the file.

2. Right-click and choose Surround SCM > Properties.

The Properties dialog box opens.

3. Select Surround SCM to view file information.

[edit] Viewing File Differences

You can compare a local file with the latest revision in Surround SCM.

1. Right-click the file and choose Surround SCM > Differences.

The compare editor displays any differences between the files.

[edit] Viewing Repository Differences

You can compare a local project folder and the corresponding repository in Surround SCM.

1. Select the project folder.

2. Right-click and select Surround SCM > Differences.

This will bring up the Repository Differences window. You can use this to see if any files are missing locally, if any files are missing in Surround SCM, and to see if any files are out of sync between the Surround SCM repository and the local project folder.

[edit] Renaming files

1. Select the file you want to rename.

2. Right-click the file and choose Surround SCM > Rename.

The Rename File dialog box opens.

3. Enter a New Name.

4. Enter any optional Comments.

5. Click OK.

The file is renamed in Surround SCM.

Note: After the file is renamed in Surround SCM you are prompted to rename the file in the project. Click Yes to rename the file and update your project to point to the new file. If you do not rename the project file you cannot work with it unless you add it to Surround SCM or manually rename it.

[edit] Refreshing file status

If you make changes to a file outside of IntelliJ IDEA, you can refresh the file to update its status. For example, if you check out a file from the Surround SCM client it will not be displayed as checked out in IntelliJ IDEA unless you refresh the file status.

1. Select the file.

2. Right-click the file and choose Surround SCM > Refresh File Status.

The file status is refreshed.

[edit] Removing files

You can remove files from Surround SCM control.

1. Select the file you want to remove.

2. Right-click the file and choose Surround SCM > Remove.

The Advanced Remove Options dialog box opens.

3. Select Destroy to delete the selected files from Surround SCM.

4. Enter any optional Comments.

5. Click OK.

The file is removed.

[edit] Disconnecting a project

IntelliJ IDEA does not have a "disconnect" from Source Control option. This has to be done manually.

This can be done by right clicking on the project root and choosing properties or by going to File > Settings. Then set the Version Control provider for the project to "None".

If you would like completely remove any reference to Surround SCM, you should also remove any of the hidden files that Surround SCM uses to keep track of its files in working directories.

1. Close IntelliJ IDEA.

2. Browse to directory where the project exists.

3. Locate and delete the .MySCMServerInfo file.

4. Browse to any subdirectories or any other directories where files used by the project may exist and delete any .MySCMServerInfo file.

NOTE: When you open IntelliJ IDEA again, the files may still have a lock icon next to them. This is because the files are still read-only. Once this attribute is removed, the lock icon will disappear from the IDE. Also, files will not be removed or destroyed from Surround SCM at this point.

[edit] Advanced Surround SCM tasks

[edit] Configuring Surround SCM preferences

You can configure a few options for the Surround SCM integration.

1. Choose File > Settings.

2. Select Version Control.

3. The Version Control window appears. Choose the Module Version Control Settings tab as shown below.

Click on the "configure" button to set preferences for every project that will be placed under Source Control, or click on the browse button ("...") next to the project to set preferences for the project only.

The Version Control Configuration window opens.

[edit] Troubleshooting IntelliJ IDEA and Surround SCM integration

This section can help you troubleshoot more common IntelliJ IDEA/Surround SCM integration problems.

Surround SCM is not included anywhere in IntelliJ IDEA

You can not find "Surround SCM" under the "Version Control" menu, or under the Version Control settings, or in the context menu of a file.

􀂄 The Surround SCM plug-in is not installed. For more information see Installing the IntelliJ IDEA plug-in.

􀂄 You are running an unsupported version of IntelliJ IDEA. The Surround SCM plug-in currently supports up to version 5.1 of IntelliJ IDEA. The integration does not work if you are running a later version of the IDE.

When a project is opened it does not prompt me to associate the project with a repository in Surround SCM

􀂄 The Surround SCM plug-in is not installed. For more information see Installing the IntelliJ IDEA plug-in.

􀂄 If this occurs after you closed a project and are opening another one, you might have clicked the "ignore all" button when the first project opened (see Sharing Projects). Open the project you wish to share with Surround SCM and close IntelliJ IDEA. When you open the IDE again it should prompt you to associate the project.

Most Surround SCM menu commands are not enabled

Add is the only enabled Surround SCM menu command in IntelliJ IDEA. Please check the following for possible causes and resolutions.

􀂄 The project is not configured correctly. Make sure the project is configured to point to a valid branch/repository. The branch/repository must also exist in the Surround SCM server you are connecting to.

􀂄 IntelliJ IDEA cannot connect to the Surround SCM server. Make sure the Surround SCM server is running and that your username/password are valid.

􀂄 The local .MySCMServerInfo file is out of sync. IntelliJ IDEA uses the .MySCMServerInfo file to determine where to look for files in Surround SCM.

Go to your project files directory and make sure the .MySCMServerInfo file data points to the correct branch/repository. If it is pointing to an incorrect branch/repository, delete it then refresh the project status to regenerate the .MySCMServerInfo file.

Files cannot be added to Surround SCM from IntelliJ IDEA You cannot add files to Surround SCM from within IntelliJ IDEA. Please check the following for possible causes and resolutions.

􀂄 The Surround SCM integration is not configured correctly for the IntelliJ IDEA project. Make sure the project points to a valid branch/repository. Surround SCM may guess where you want to add the files, based on the information in the .MySCMServerInfo file. However, the add cannot be completed if the .MySCMServerInfo file does not exist.

􀂄 Your IntelliJ IDEA project configuration points to the wrong branch. This can be an issue if you maintain the IntelliJ IDEA local project files in Surround SCM then branch the repository that contains the project files. The local files point to the old branch, which is where the files are added. Configure IntelliJ IDEA to point to the correct branch then add the files to Surround SCM.