Search:     Advanced search

Surround SCM Xcode 4 Integration

Article ID: 762  |  Last updated: 04 May, 2017

Surround SCM 2012.0 - 2015.1.0 supports integration with Xcode 4.x.

This article includes information about the integration requirements, installing the plug-in, associating projects with Surround SCM, setting integration options, performing Surround SCM actions, opening multiple source control projects, and troubleshooting.

Note: The following information only applies to Xcode 4. See Surround SCM Xcode 3 Integration if you use Xcode 3.


  • Changelists must be enabled in Surround SCM. The Xcode plug-in uses changelists for all check in and add operations. Files are automatically added to a default Xcode changelist when they are added to a project and are not available in Surround SCM until the changelist is committed.
  • Checking in files without check out must be enabled in Surround SCM.

Installing the plug-in

The Xcode plug-in is installed during Surround SCM Client installation. If you did not install it, close Xcode, rerun the installer, and select the Xcode 4 integration option.

Associating projects with Surround SCM

You can associate a project with Surround SCM when you open a project from a Surround SCM working directory, add a working copy in Xcode, or get the project in Xcode.

Opening a project from a Surround SCM working directory

  1. In Surround SCM, select the project repository. If the project is not already in Surround SCM, create a repository for it and then recursively add the project files.
  2. Choose Repository > Set Working Directory. The Set Working Directory dialog box opens.
  3. Click Browse to select the local directory to store the project files in.
  4. Select Allow child repositories to inherit this working directory and Get files to working directory.
  5. Click OK. The working directory is set and the project files are retrieved to it.
  6. In Xcode, open the project from the directory you set as the working directory. Xcode automatically detects the project is controlled by Surround SCM. You may be prompted to connect to Surround SCM before you can perform Surround SCM actions.

Adding a working copy in Xcode

  1. In the Repositories pane in the Xcode Organizer, add a remote repository path using the address to the project repository in Surround SCM (e.g., sscm://ServerAddress:Port//Branch//Repository/Subrepository).
  2. Click the + button next to the remote repository and choose Add Working Copy.
  3. Select the project root folder from the file browser to ensure Xcode associates all project files with Surround SCM and click Add Working Copy.

Getting the project in Xcode

In Xcode, check out a project or add a repository to get files from Surround SCM.

Checking out a project

Note: Xcode’s Checkout command is the same as Surround SCM’s Get command.

  1. In the Welcome to Xcode dialog box, click Connect to a repository
    In the Repositories pane in the Xcode Organizer, click the + button and choose Checkout or Clone Repository.
    The Checkout or Clone dialog box opens.
  2. Enter the Surround SCM sscm:// address for the project’s root repository as the Location and click Checkout.
  3. If a working directory is not set for the repository, you are prompted to set it.
  4. Click Yes. Xcode retrieves the files to the working directory.
  5. Click Open Project when check out is complete.

Adding a repository

  1. In the Repositories pane in the Xcode Organizer, click the + button and choose Add Repository. The Add a Repository dialog box opens.
  2. Enter the repository name and Surround SCM sscm:// address as the Location.
  3. Click Next. You may be prompted to log in to Surround SCM.
  4. Click Add. The repository is added to the Xcode Organizer.
    Note: You do not need to enter trunk, branches, or tags information because the plug-in does not support branching.
  5. Select Root under the repository.
  6. Browse to the repository to get and click Checkout. Xcode retrieves the files to the working directory.

Setting Xcode integration user options

You can set user options for committing changelists and to specify the file types Surround SCM should ignore.

  1. In Surround SCM, choose Tools > Users Options and select the Xcode Integration category.
  2. Select Display the TestTrack Browser dialog before all changelist commit operations to always open the TestTrack Browser to attach files to TestTrack items before committing changes.
  3. Enter any file extensions in the Ignored Files field to exclude files when committing changelists.
  4. Click OK to save the changes.

Performing Surround SCM actions

Select a file in the project navigator and choose an action from the File > Source Control menu.

Xcode uses the following status badges to display local file status, which can help you determine if files are in sync with Surround SCM.

  • M — The local file was modified and does not match the file in Surround SCM.
  • U — A newer file version was checked in and the local file is no longer current.
  • A — The file is not in Surround SCM and is in the default Xcode pending changelist.
  • I — The file is ignored by Surround SCM based on the integration user options.
  • ! — The file is not in Surround SCM. Only visible in the Commit dialog box.
  • - — The files in the folder have different statuses. Expand the folder for details.
  • ? — The file status cannot be determined.

Opening multiple source control projects

You can open multiple projects associated with Surround SCM at once. For example, you may need to work with two projects stored on different Surround SCM Servers. When prompted for your Surround SCM username and password, you can specify how to use the specified credentials.

  • Always login with this username and password automatically connects to Surround SCM using the credentials each time you open an associated project.
  • Use login settings only for this session uses the credentials for all associated projects opened before closing Xcode. When you close Xcode, the session ends and the credentials are cleared.
  • Do not remember login settings always prompts for credentials when opening associated projects.


Host is unreachable

A host is unreachable error may be displayed if you use an IP address to connect to Surround SCM when associating a new repository or opening a project. Replace the IP address with the Surround SCM Server hostname to establish the association.

Article ID: 762  |   Last updated: 04 May, 2017

Prev   Next
Visual Studio Integration for the Alternative Surround SCM...     Surround SCM Jenkins Integration