p4 depot

Synopsis

Create or edit a depot specification.

Warning

A branch, depot, label, and workspace may not share the same name.

Syntax

p4 [g-opts] depot [-t type] depotname
p4 [g-opts] depot -d [-f] depotname
p4 [g-opts] depot -o [-t type] depotname
p4 [g-opts] depot -i

Description

The Perforce versioning service stores files in shared repositories called depots. By default, there is one depot on every Perforce installation, and its name is depot.

To create or edit a depot, use p4 depot depotname and edit the fields in the depot spec form. Depots can be of type local, stream, remote, archive, spec, unload or tangent.

Specifying the -t option creates a depot spec that is custom-made for the depot type you specify. For example, the following command: 

$ p4 depot -o [-t stream] mystreamdepot

Creates the following depot spec:

Depot:        mystreamdepot
Owner:        user
Date:         2015/07/21 15:57:50
Description:  Created by user.
Type:         stream
StreamDepth:  //mystreamdepot/1
Map:          mystreamdepot/...

You can edit this spec or you can pipe the output stream to the p4 depot command as follows to create the depot: 

$ p4 depot -o [-t stream] mystreamdepot | p4 depot -i

A depot created with p4 depot is not physically created on disk until files have been added to it with p4 add. Users are not able to access a new depot created with p4 depot until permission to access the depot is granted with p4 protect.

Form Fields

Field Name Type Description

Depot:

Read-Only

The depot name as provided in p4 depot depotname.

Owner:

Writable

The user who owns the depot. By default, this is the user who created the depot.

The specified owner does not have to be a Perforce user. You might want to use an arbitrary name if the user does not yet exist, or if you have deleted the user and need a placeholder until you can assign the spec to a new user.

Description:

Writable

A short description of the depot’s purpose. Optional.

Type:

Writable

local, remote, spec, stream, unload, archive or tangent.

A local depot is writable, and is the default depot type. Files reside in the server’s root directory and are managed directly by the server.

A stream depot is also writable, but contains streams, a type of branch that includes hierarchy and policy.

A remote depot references files that reside on other servers, and cannot be written to. See Working with Remote Depots for more information.

The spec depot, if present, automatically archives edited forms. See Working with Spec Depots for more information.

The unload depot, if present, holds infrequently-used metadata (about old client workspaces and labels) that has been unloaded with the p4 unload command. For more information, see the Helix Versioning Engine Administrator Guide: Fundamentals.

An archive depot is used in conjunction with the p4 archive and p4 restore commands to facilitate offline (or near-line) storage of infrequently-accessed revisions, typically large binaries.

A tangent depot defines a read-only location that holds tangents created by the p4 fetch -t command. The tangent depot named tangent is automatically created by p4 fetch -t if one does not already exist.

Address:

Writable

If the Type: is remote, the address should be the P4PORT address of the remote server.

If the Type: is local or spec, this field is ignored.

Suffix:

Writable

If the Type: is spec, this field holds an optional suffix for generated paths to objects in the spec depot. See Working with Spec Depots for more information.

The default suffix is .p4s. You do not need a suffix to use the spec depot, but supplying a file extension to your Perforce server’s versioned specs enables users of GUI client software to associate Perforce specifications with a preferred text editor.

If the Type: is local or remote, this field is ignored.

StreamDepth:

Writable

For stream depots, the optional depth to be used for stream paths in the depot, where depth specifies the number of slashes following the depot name of a stream. See Working with Stream Depots.

This field is used when streams are being created. The default is 1, matching the traditional stream name. You cannot update this value once streams or archive data exist in a depot.

Map:

Writable

If the Type: is local, spec, or archive, set the map to point to the relative location of the depot subdirectory. The map must contain the ... wildcard; for example, a local depot new might have a Map: of new/....

If the Type: is remote, set the map to point to a location in the remote depot’s physical namespace, for example, //depot/new/rel2/.... This directory will be the root of the local representation of the remote depot.

For more information, see Providing Map Information.

SpecMap:

Writable

For spec depots, an optional description of which specs should be saved, expressed as a view.

Options

-d depotname

Delete the depot depotname. The depot must not contain any files; the Perforce superuser can remove files with p4 obliterate.

If the depot is remote, p4 obliterate must still be run: no files are deleted, but any outstanding client or label records referring to that depot are eliminated.

The name of a depot may not be the same as the name of a branch, client workspace, or label.

-f

By default, when you delete a depot, the directory specified by the Map: field (typically under P4ROOT) must be empty. Use the -f option to remove all files even if the directory is not empty.

-i

Read a depot specification from standard input.

-o depotname

Write a depot specification to standard output.

-t type

The type of the depot: local, remote, spec, stream, unload, archive or tangent.

g-opts

See “Global Options”.

Usage Notes

Can File Arguments Use Revision Specifier? Can File Arguments Use Revision Range? Minimal Access Level Required

N/A

N/A

super

Providing Map Information

For a local depot, the Map field specifies the filesystem location of the archive contents for files in the depot. This location can be either relative or absolute. To store a depot’s versioned files on another volume or drive, specify an absolute path in the Map field. This path need not be under P4ROOT.

  • If the location is absolute, for example, /p4/depots/depot/..., no further interpretation is needed.

  • If the location is relative, for example, Ace/..., the location is interpreted relative to the value of P4ROOT, unless the server.depot.root configurable is set, in which case it is interpreted relative to the value of that variable.

    Take care if you introduce the server.depot.root form of addressing in an existing installation. If you want to set it to a value other than P4ROOT, you should first update your existing depot Map values to make sure they are all absolute. You can then set the server.depot.root variable without disrupting anything. After that, you can go back and update your existing depot maps if you so desire.

Working with Remote Depots

If you are using remote depots, the machine that hosts the Perforce service (that is, the machine specified in P4PORT) is configured to permit your Perforce application to read files from a different Perforce service. Remote depots are restricted to read-only access; Perforce applications cannot add, edit, delete, or integrate files in the depots on the other servers. For more information about remote depots, see the Helix Versioning Engine Administrator Guide: Fundamentals.

Remote depots are accessed by a virtual user named remote (or, if configured, by the service user configured for the service that originates the request), and by default, all files on any Perforce installation can be accessed remotely. To limit or eliminate remote access to a particular server, use p4 protect to set permissions for user remote (or the accessing site’s service user) on that server.

For example, to eliminate remote access to all files in all depots on a particular server, set the following permission on that server:

read user remote * -//...

Because remote depots can only be used for read access, it is not necessary to remove write or super access.

Neither service users nor the virtual remote user consume Perforce licenses.

If your server accesses remote depots by means of a service user, your service user must have a valid ticket for the server that is hosting the remote depot.

Working with Spec Depots

The spec depot, if present, tracks changes to user-edited forms such as client workspace specifications, jobs, branch mappings, and so on. There can be only one spec depot per server. Files in the spec depot are automatically generated by Perforce, and are represented in Perforce syntax as follows:

//specdepotname/formtype/objectname[suffix]

For instance, if the spec depot is present and named spec, and uses the default suffix of .p4s, you can obtain the history of changes to job000123 by typing:

p4 filelog //spec/job/job000123.p4s

After you have created the spec depot, use p4 admin updatespecdepot to pre-populate it with current set of client, depot, branch, label, typemap, group, user, and job forms. For more information about setting up a spec depot, see the Helix Versioning Engine Administrator Guide: Fundamentals.

For spec depots, the SpecMap: field can be used to control which specs are versioned. By default, all specs (//spec/...) are versioned. To exclude the protections table from versioning, configure the spec depot’s SpecMap: as follows: 

SpecMap:
    //spec/...
    -//spec/protect/...

Adding or changing the spec mapping only affects future updates to the spec depot; files already stored in the spec depot are unaffected.

Working with Stream Depots

You use a stream depot to store the streams you create and work with. You need to provide the following information when creating a stream depot: name, owner, date, type, and stream depth.

By default, the stream depth is 1, which specifies that streams are stored one level below the depot name. For example: 

//myStreamDepot/myStream1
//myStreamDepot/myStream2
//myStreamDepot/myStream3

You can specify a different depth when you create the stream depot. This determines the subdirectory level where you want to root your streams. For example, if you specify 3 for StreamDepth, your depot might look like one of these: 

//myStreamDepot/A/B/myStream1
//myStreamDepot/A/B/myStream2
//myStreamDepot/A/C/myStream3

You might want to increase the stream depth to identify the project to which your streams belong or to identify the organizational group that is responsible for those streams. In general, it is best to keep the depth as low as possible.

Observe the following limitations with respect to stream depth:

  • All streams in a stream depot must be rooted at the same subdirectory level, which is given by the value of StreamDepth.

  • You may not change the name of a stream.

    For example if a stream is named as follows:

    //myStreamDepot/A/B/myStream1

    You cannot rename it either to this (changing the depth of the stream):

    //myStreamDepot/A/myStream1

    or this:

    //myStreamDepot/A/B/myNewStream

Related Commands

To list all depots known to the Perforce versioning service

p4 depots

To populate a new depot with files

p4 add

To add mappings from an existing client workspace to the new depot

p4 client

To remove all traces of a file from a depot

p4 obliterate

To limit remote access to a depot

p4 protect

To archive files into an archive depot

p4 archive

To restore files from an archive depot

p4 restore