Perforce Public Knowledge Base - Specification Names
Downloads Blog Company Integrations Careers Contact Try Free
Menu Search
Reset Search



Specification Names

« Go Back



What name should I use for my client/label/branch/group/user/depot specification?

Are there any restrictions on specification names?

What is the maximum number of characters (or bytes) I can use for the name of a spec? Is there a limitation?

Why do I see an error with newer Perforce server versions regarding my specification name, when they worked for older versions of Perforce?


There are two principle areas of naming Perforce specification objects to consider:

  • Names suitable for Perforce.
  • Names suitable for the underlying operating system.

Names that are suitable for Perforce

In general, any ASCII (or printable non-ASCII if the Server is Unicode-enabled) can be used but the following is not recommended or not allowed depending on the type of Perforce object:

  • Initial dash character
  • Non-printable characters
  • Revision chars (@, #)
  • Slashes (/)
  • Commas (,)
  • Null directory (//)
  • Relative paths (., ..)
  • Wildcards (*, %%%%x, ...)
  • Purely numeric name

There is a maximum string length for spec names: you cannot create a spec (client workspace, label, and so on) with a name longer than 1024 bytes when encoded in UTF-8.

Please note that the pathname component separator (/) is not permitted in filenames, depot names, or client workspace names, but can appear in label names, job names, or user names. The recursive subdirectory wildcard (...) is not permitted in file names, label names, or other identifiers. For more information, refer to Limitations on characters in filenames and entities in Command Reference.

Names that are suitable for the OS

Perforce uses the native operating system to manage files. The name you choose might be valid within Perforce, but the operating system's file system might not support it. This is a problem when you have a spec depot, which versions all specs (client, group, depot, user, label) like any other file in the repository. If, for example, you use a character in a username that is not acceptable as part of a filename on your chosen operating system, you might see "can't write to spec depot" errors when Perforce tries to create that user spec.

Note: You would still be able to use the specification within Perforce, but running p4 verify against the spec depot can result in "MISSING!" errors as the corresponding spec file has not been created.

What are "unacceptable" characters?

The spec depot contains versioned files just like a traditional depot. It is possible that there are filenames in a traditional depot that contain illegal characters if your system environment is heterogeneous (for example, a Windows server and Linux client). Below is a list of unacceptable characters on Windows systems. Unix systems will generally allow these characters although they might need to be escaped or quoted.

? [ ] / \ = + < > : ; " , *

Why did it work before, using my old Perforce Server?

While earlier versions of Perforce would permit the use of problematic characters in specification names, the results could be unexpected. For example, it was possible to use slashes (/) in client names in server versions 2005.2 and earlier:

p4 client usr/myData
Client usr/myData saved.

Since forward slashes are used as delimiters within Perforce this could cause some serious issues where the incorrect records would be deleted, and others not deleted when they should be. Consider this list of clients:

This becomes even more complex if there are directories at the top level of Perforce named "project_foo" or "project_bar". Attempting to use slashes in client names in Perforce server versions 2006.1 and later now produces an error:


p4 client usr/myData
Slashes (/) not allowed in 'usr/myData'.
There are still characters that Perforce will permit, but can cause issues depending on your operating system. Assume a label called "label:2081105". This label is still created as of server version 2009.2. Information about the label is stored in the metadata within the Perforce database, and you can see this label using p4 labels.

However, if you are using a spec depot, the label spec is saved as a file in your local filesystem. The label name is used to name the file, so if that name is not compatible with the requirements of the local filesystem you see a problem. In this case, Unix allows the ':' character in a filename, but Windows does not. The error message states "Warning: couldn't archive to spec depot", so although the label is created in the system, the label spec is not saved in the spec depot. The metadata is still there (and is usable), but you would still get "MISSING!" errors from a p4 verify of the spec depot as there is no corresponding archive file.

In short, on a Windows-based system your label is created, but the label-spec is not.

How do I fix this, and how do I keep it from happening again?

You would need to remove these specifications from Perforce. This might require a p4 obliterate, as deleting the specification simply marks the head revision as deleted. Before obliterating, it is advisable to discuss the situation with Perforce Support, as there might be other issues to consider.

To prevent this from happening in future, you could implement form triggers to check that reserved characters are not used in the specification names. While Perforce has added some restrictions on many characters, differences between platforms require some flexibility in naming conventions.

There are other points to note if you are working in a mixed-platform environment, as described in the KB articles linked here.

Related Links



Was this article helpful?



Please tell us how we can make this article more useful.

Characters Remaining: 255