Creating and managing workspaces

A workspace specification defines the portion of the depot that can be accessed from that workspace and specifies where local copies of files in the depot are stored. This location is called the workspace (or client, in the Perforce command line interface). A computer can contain multiple workspaces. A workspace is required when connecting to a Perforce service if you intend to work with files. You can connect using only host name and port, but you cannot exchange files unless you specify a workspace.

The mapping of depot files to local files is called the workspace view. If you are working with streams, the workspace view is generated by Perforce, based on the structure of the stream. If the structure of the stream changes, the workspace view is updated automatically. (In fact, you cannot manually edit the view of a stream workspace.) If you use classic depots, you must define and maintain the workspace view manually.

For more information about streams, see the "Streams" chapter in the Helix Versioning Engine User Guide .

Create a workspace

To create a new workspace:

  1. Open the Workspace dialog by doing one of the following:

    • Go to Connection > New Workspace…​.
    • Context-click a stream in the Streams tab and select New Workspace…​.
    • Context-click in the Workspaces tab and select New Workspace…​.
  2. On the Basic tab, accept or change the default workspace name and root.
  3. Map the workspace to the depot:

    Classic depots: You can configure the workspace view (mappings) in the Workspace Mappings field by doing one of the following:

    • Select the View workspace mapping as text TextEdit icon and enter your view specification using Perforce client view syntax.
    • Select the View workspace mapping as tree TreeEdit icon and browse to the files and folders you want.

      Build your workspace mapping by selecting a depot, folder, or file and using the Include, Exclude, and Clear icons; or context-click and select include, exclude, and clear options in the context menu.

      For more information about mapping workspaces, see Defining a Workspace View.

      Stream depots:

    • Stream: enter or browse for the stream that will be associated with this workspace.

      If you enter a stream, the workspace view is populated automatically under Workspace Mappings; you cannot edit it.

      Note

      To dissociate a workspace from a stream, delete the entry in the Stream field.

    • Stream at change:if you want to work using a stream definition as of a specific changelist, enter the changelist number here.

      When a change is made to a stream definition, the stream is versioned using the current value of the change counter. Use stream at change when you want your stream workspace to use a view generated from the stream definition as of a prior changelist.

      Using a stream-at-change view is useful if you need to work with a set of directories and files that are not identical to the set in the current stream. For example, your stream may no longer include certain libraries that had been included in an early version of the stream, but now you need those libraries to test a build. Enter the number of the last changelist to include those libraries. When you work in this workspace, Perforce syncs to that changelist, allowing you to perform the test builds. Stream-at-change workspaces are read-only; you cannot check files into a previous changelist.

      For more information about streams, see the "Streams" chapter in the Helix Versioning Engine User Guide.

  4. Advanced options: You can specify the following settings on the Advanced tab.

    Owner

    The user who created the specification.

    Locked

    If enabled, only the owner of the workspace can use, change, or delete the workspace specification.

    Description

    Your own explanation of the purpose of the workspace, or any related information you need to specify.

    Host

    (Optional) The computer where the workspace resides. To enable the workspace to be used from any machine, leave this field blank.

    AltRoots

    For workspace specifications used from hosts on different platforms, a list of workspace roots in host-platform-specific syntax.

    File Options

    • Allwrite: All files in the workspace are writable (can be modified).
    • Clobber: Syncing files overwrites writable files on the workspace.
    • Compress: Compresses data sent between the workspace and the Perforce server.
    • Modtime: Modification time for files edited in the client workspace is set to the time when the file is submitted to the depot.
    • Rmdir: Deletes a workspace folder if all the files contained in the folder are removed.

    Line ending characters for text files:

    The line-end convention used for storing text files on the workspace computer:

    • Local: Uses the workspace platform default
    • Unix: LF
    • Mac: CR
    • Win: CRLF
    • Share: Line endings are LF. Any CR prior to a line ending is removed for storage or syncing (for disks shared between UNIX and Windows)

    On submit:

    Configures what happens when users submit files.

  5. Click Save to save your entries and create the workspace specification.

Change your workspace

Classic depots:

You can switch your workspace using the Select Workspace dialog. Open the Select Workspace dialog by doing any of the following:

  • In the drop-down menu at the top of the Tree pane, click the drop-down arrow and select Switch to Workspace…​.
  • Go to Connections > Switch to Workspace…​.
  • Open the Open Connection dialog and click Browse next to the Workspace field.

You can also switch your workspace by context-clicking a workspace in the Workspaces tab and selecting Switch to Workspace <workspace name>.

Stream depots:

You can switch stream workspaces using the same methods as you use for classic workspaces. In addition, you can switch stream workpaces by doing the following:

  • Context-click a stream and select Work in this Stream…​.
  • Merge or copy to a stream: you are prompted to switch to the target stream’s workspace.

In both cases, a warning dialog pops us and asks you to switch workspaces or create a new one. Click the Switch Workspaces button to switch your workspace. If more than one workspace is associated with the stream, the Select Workspace dialog opens, where you can search for and select the workspace you want.

However, if you have set your stream operations preference in the Preferences dialog to use the same workspace when you switch between streams, then P4V does not prompt you to switch workspaces. Instead the workspace view changes to include the stream you are switching to. In other words, the Stream field value in the workspace definition changes to the new stream. No matter what your stream operations preference, this is always the behavior in the Streams graph when you drag the Workspace workspaces icon from your current stream to the one you want to work in.

View workspaces

To view workspaces for the server to which you are connected, do either of the following:

  1. Go to View > Workspaces or select the Workspace workspaces icon in the toolbar to open the Workspaces tab.

    Click a workspace row to display the details of the client workspace specification.

  2. Open the Select Workspace dialog.

    Click a workspace row to display the details of the client workspace specification.

Search for workspaces

You can use filters to search for workspaces on the Workspaces tab and the Select Workspace dialog. You can filter workspaces by any combination of the following:

  • Owner: select current user or enter a user ID.
  • Workspace Name
  • Stream name

You can also choose to Show only workspaces available for use on this computer.

For more information on filters, see Searching and filtering.

Delete and unload workspaces

Deleting a workspace removes Perforce’s record of the workspace but does not remove files from the workspace or depot. You cannot delete a workspace that has files checked out (open for edit) in Perforce.

To delete a workspace:

  1. Submit or revert any pending or shelved changelists associated with the workspace.
  2. Go to View > Workspaces or select the Workspace workspaces icon in the toolbar to open the Workspaces tab.
  3. Context-click the label and select Delete Workspace 'workspace_name'.

Unloading transfers infrequently-used metadata from the versioning engine’s database files to a set of flat files in an unload depot. If you unload a workspace, you can reload it if you change your mind and want to use it again.

To unload a workspace:

  1. Submit or revert any pending or shelved changelists associated with the workspace.
  2. Go to View > Workspaces or select the Workspace workspaces icon in the toolbar to open the Workspaces tab.
  3. Context-click the workspace and select Unload Workspace 'workspace_name''.

To reload an unloaded workspace:

  1. Go to View > Workspaces or select the Workspace workspaces icon in the toolbar to open the Workspaces tab.
  2. Select the unloaded Unloaded…​ icon in the filter pane to open the Unloaded Workspaces dialog, where you can filter for and select unloaded workspaces to reload.
  3. Context-click the workspace and select Reload Workspace 'workspace_name'.

For more information about unloading, see the Perforce Command Reference.

Defining a Workspace View

The workspace view determines which portions of the depot are visible in your Workspace Tree and where local copies of depot files are stored in your workspace. If you use streams, the workspace view is generated and updated automatically. If you use classic depots, you must maintain the view manually, as described in this topic.

To define or change your workspace view:

  1. Go to View > Workspaces or click the Workspaces workspaces icon in the toolbar.
  2. In the Workspaces tab, context-click the workspace and select Edit Workspace.
  3. In the Workspace form, edit the Workspace Mappings field.

    You can define the view syntactically and graphically, as described below.

  4. When you have finished editing, save your changes.

Syntactic view specification

Click the View workspace mapping as textTextEdit icon and type your view specification using Perforce client view syntax. Views consist of mappings, one per line. The left-hand side of the mapping specifies the depot files and the right-hand side specifies the location in the workspace where the depot files reside when they are retrieved from the depot. Example:

//depot/...         //bruno/depot/...
//user_depot/...    //bruno/user_depot/...
//projects/...      //bruno/myprojects/...

For details about client view syntax, see the P4 User’s Guide.

Graphical view specification

Click the View workspace mapping as tree TreeEdit icon. The depot is displayed as a tree of folders and files. Context-click the file or folder you want to map and choose the mapping, as follows:

  • Include tree/Exclude tree: include or exclude all files below the selected folder .
  • Include file/Exclude file: include or exclude a specific file.
  • Include Special/Exclude Special: use Perforce syntax to specify the workspace view.

Alternately, double-click files or folders and use the resulting Special Edit dialog to define the view. This dialog enables you to specify options by clicking radio buttons or using the Expressions field to enter the left and right-hand components of a client view mapping.

Tip

To quickly add a depot path to the client view, go to View > Filter Depot > Entire Depot Tree, context-click the desired path and choose Map to Workspace View…​