P4 struct

The P4 struct provides a Go interface for the P4 Server client API. Each P4 struct allows you to interact with the P4 Server in a thread-safe manner. The typical workflow is as follows:

1. Instantiate your P4 object.

2. Specify your P4 Server client environment.

   • Client
   • Host
   • Password
   • Port
   • User

3. Connect to the Perforce service.

4. Run your P4 Server commands.
5. Disconnect from the Perforce service.

Table of methods

P4 is the main struct used for executing Perforce commands. Most commands within Go use the following methods.

1
2
3
p4.SetInput(p4.FormatSpec(spec, specdict))
args = append([]string{"-i"}, args...)
result, err := p4.Run(spec, args...)

Examples

Initialization and Cleanup

• New() -> *P4

Creates and returns a new instance of the P4 struct. This method initializes the Perforce client API and prepares it for use.

p4 := New()
defer p4.Close()
fmt.Println("Perforce client initialized.")

• Close()

Cleans up resources associated with the P4 instance, including handlers and the client API. This method should always be called when the P4 instance is no longer needed to avoid resource leaks.

p4 := New()
defer p4.Close()
// Perform operations with the Perforce client
fmt.Println("Perforce client closed.")

Connection Management

• Connect() -> (bool, error)

Establishes a connection to the P4 Server. This method is used to authenticate and connect the client to the server.

connected, err := p4.Connect()
if err != nil {
    fmt.Println("Failed to connect:", err)
} else if connected {
    fmt.Println("Connected to P4 server.")
}

• Connected() -> bool

Checks if the client is currently connected to the P4 Server. This method is useful for verifying the connection status before executing commands.

if p4.Connected() {
    fmt.Println("Client is connected.")
}

• Disconnect() -> (bool, error)

Disconnects from the P4 Server. This method is used to cleanly terminate the connection to the server.

disconnected, err := p4.Disconnect()
if err != nil {
    fmt.Println("Failed to disconnect:", err)
} else if disconnected {
    fmt.Println("Disconnected from P4 server.")
}

Server Information

• Identify() -> string

Return the version of P4 API for Go that you are using.

fmt.Println("Server ID:", p4.Identify())

• ServerLevel() -> int

Retrieves the server level, which indicates the version or capabilities of the P4 Server. This method is useful for determining if certain features are supported by the server.

level, err := p4.ServerLevel()
if err != nil {
    fmt.Println("Error in getting server level:", err)
}
fmt.Println("Server Level:", level)
if level >= 33 {
    fmt.Println("Server supports unload depots.")
}

• ServerUnicode() -> bool

Checks if the server supports Unicode. This method is used to determine if the server is operating in Unicode mode, which is important for handling internationalized text.

result, err := p4.ServerUnicode()
if err != nil {
    fmt.Println("Error in server unicode:", err)
}
if result {
    fmt.Println("Server is running in Unicode mode.")
} else {
    fmt.Println("Server is not running in Unicode mode.")
}

• ServerCaseSensitive() -> bool

Checks if the server is case-sensitive. This method is useful for understanding how the server treats file names and paths, especially in environments where case sensitivity matters.

result, err := p4.ServerCaseSensitive()
if err != nil {
    fmt.Println("Error in case-sensitive:", err)
}
if result {
    fmt.Println("Server is case-sensitive.")
} else {
    fmt.Println("Server is not case-sensitive.")
}

Command Execution

• Run(cmd string, args ...string) -> []P4Result

Executes a Perforce command with the specified arguments and returns the results as a slice of P4Result. This is the most generic method for running commands and is used for commands like info, sync, files, etc.

results, err := p4.Run("info")
fmt.Println("Server Info:", results)

• RunFetch(spec string, args ...string) -> (Dictionary, error)

Fetches a Perforce spec (for example, client, label, branch) and returns it as a dictionary. This method is used to retrieve the current configuration or details of a specific spec.

clientSpec, err := p4.RunFetch("client")
if err == nil {
    fmt.Println("Client Spec:", clientSpec)
}

• RunSave(spec string, specdict Dictionary, args ...string) -> (*P4Message, error)

Saves a Perforce spec (for example, client, label, branch) using the provided dictionary. This method is used to update or create a new spec in the P4 Server.

clientSpec["Root"] = "/new/root"
msg, err := p4.RunSave("client", clientSpec)
if err == nil {
    fmt.Println("Client saved:", msg.String())
}

• RunSubmit(args ...interface{}) -> ([]Dictionary, error)

Submits a changelist or files to the P4 Server. This method is used to finalize changes and make them part of the Perforce depot.

changeSpec, _ := p4.RunFetch("change")
changeSpec["Description"] = "Submitting changes"
_, err := p4.RunSubmit(changeSpec)

• RunShelve(args ...interface{}) -> ([]Dictionary, error)

Shelves files or changelists in the P4 Server. Shelving allows you to temporarily store changes without submitting them.

changeSpec, _ := p4.RunFetch("change")
changeSpec["Description"] = "Shelving changes"
_, err := p4.RunShelve(changeSpec)

• RunDelete(spec string, args ...string) -> (*P4Message, error)

Deletes a Perforce spec (for example, client, label, branch). This method is used to remove configurations or objects from the P4 Server.

msg, err := p4.RunDelete("client", "my_client")
if err == nil {
    fmt.Println("Client deleted:", msg.String())
}

• RunFilelog(args ...string) -> ([]*P4DepotFile, error)

Retrieves the file history for a specified file or set of files. This method is used to analyze the revision history, changes, and integrations of files.

filelog, _ := p4.RunFilelog("//depot/file.txt")
for _, file := range filelog {
    fmt.Println("File:", file.Name)
}

// Process the filelog output
for _, df := range filelog {
    // Print depot file name
    fmt.Println("Depot File:", df.Name)

    // Iterate through revisions
    for _, rev := range df.Revisions {
        fmt.Println("\nRevision Details:")
        fmt.Println("  Revision Number:", rev.Rev)
        fmt.Println("  Change Number:", rev.Change)
        fmt.Println("  Action:", rev.Action)
        fmt.Println("  Type:", rev.Type)
        fmt.Println("  User:", rev.User)
        fmt.Println("  Client:", rev.Client)
        fmt.Println("  Description:", rev.Desc)
        fmt.Println("  Time:", rev.Time)

        // Print integrations (if any)
        if len(rev.Integrations) > 0 {
            fmt.Println("  Integrations:")
            for _, integ := range rev.Integrations {
                fmt.Println("    How:", integ.How)
                fmt.Println("    File:", integ.File)
                fmt.Println("    Start Revision:", integ.SRev)
                fmt.Println("    End Revision:", integ.ERev)
            }
        }
    }
}

• RunLogin(args ...string) -> (Dictionary, error)

Logs in to the P4 Server using the current password. This method is used to authenticate the client with the P4 Server.

loginResult, err := p4.RunLogin()
if err == nil {
    fmt.Println("Login successful:", loginResult)
}

• RunPassword(old string, new string) -> (*P4Message, error)

Changes the user's password. This method is used to update the password for the current user.

msg, err := p4.RunPassword("", "newpassword")
if err == nil {
    fmt.Println("Password updated:", msg.String())
}

• RunTickets() -> ([]map[string]string, error)

Reads the Perforce tickets file and returns a list of tickets. This method is used to retrieve authentication tickets stored locally.

tickets, err := p4.RunTickets()
if err == nil {
    fmt.Println("Tickets:", tickets)
}

Spec Parsing and Formatting

• ParseSpec(spec string, form string) -> Dictionary

Parses a Perforce spec (for example, client, label, branch) from a string into a Dictionary. This method is used to convert a raw spec string into a structured format for easier manipulation.

rawSpec := `
Client: test_client
Root: /workspace
Options: noallwrite noclobber nocompress unlocked nomodtime normdir
View:
    //depot/... //test_client/...
`
parsedSpec, err := p4.ParseSpec("client", rawSpec)
fmt.Println("Parsed Spec:", parsedSpec)

• FormatSpec(spec string, dict Dictionary) -> string

Formats a Dictionary into a Perforce spec string. This method is used to convert a structured spec back into a raw string format for saving or submission.

specDict := Dictionary{
    "Client": "test_client",
    "Root":   "/workspace",
    "Options": "noallwrite noclobber nocompress unlocked nomodtime normdir",
    "View0":  "//depot/... //test_client/...",
}
formattedSpec, err := p4.FormatSpec("client", specDict)
fmt.Println("Formatted Spec:\n", formattedSpec)

• SpecIterator(spec string, args ...string) ([]Dictionary, error)

The SpecIterator method retrieves a list of Perforce specs (for example, client, label, branch) and iterates over them to fetch detailed information for each spec. It returns the results as a slice of Dictionary objects, where each dictionary represents a single spec with its key-value pairs.

This method is particularly useful for retrieving and processing multiple specs of a specific type (such as, all clients, all labels) in a structured format.

Supported spec types are:

• clients

• labels

• branches

• changes

• streams

• jobs

• users

• groups

• depots

• servers

• ldaps

• remotes

// Example : Retrieve the first 5 labels.

labels, err := p4.SpecIterator("labels", "-m", "5")
if err != nil {
    fmt.Println("Error fetching labels:", err)
    return
}

// Print label details
for _, label := range labels {
    fmt.Println("Label:", label["Label"])
    fmt.Println("Owner:", label["Owner"])
    fmt.Println("Description:", label["Description"])
    fmt.Println("----")
}

Configuration Management

• SetInput(input ...string)

  Sets the input for the nextPerforce command. This method is useful for commands that require user input, such as submitting a changelist, resolving conflicts, or creating specs. The input provided will be consumed by the next command executed via the Run method.

  Copy

  // Example : Use SetInput to provide the changelist description 
  // or other required input for the submit command.
  changeSpec, _ := p4.RunFetch("change")
  changeSpec["Description"] = "Submitting changes via SetInput"
  formattedSpec, err := p4.FormatSpec("change", changeSpec)
  p4.SetInput(formattedSpec)
  result := p4.Run("submit", "-i")
  fmt.Println("Submit Result:", result)

• SetEnv(env string, value string)

  Sets an environment variable for the Perforce client.

  Copy

  _, err := p4.SetEnv("P4PORT", "perforce:1666")
  fmt.Println("P4PORT set to:", p4.Env("P4PORT"))

• Env(env string) -> string

  Retrieves the value of an environment variable.

  Copy

  fmt.Println("P4PORT:", p4.Env("P4PORT"))

• SetEnviroFile(enviroFile string)

  Sets the path to the Perforce environment file.

  Copy

  p4.SetEnviroFile("/path/to/enviro")
  fmt.Println("Enviro file set to:", p4.EnviroFile())

• EnviroFile() -> string

  Retrieves the path to the Perforce environment file.

  Copy

  fmt.Println("Enviro file path:", p4.EnviroFile())

• SetCharset(charset string)

  Sets the character set for the Perforce client.

  Copy

  _, err := p4.SetCharset("utf8")
  fmt.Println("Charset set to:", p4.Charset())

• Charset() -> string

  Retrieves the current character set.

  Copy

  fmt.Println("Current charset:", p4.Charset())

• SetCwd(cwd string)

  Sets the current working directory for the Perforce client.

  Copy

  p4.SetCwd("/path/to/workspace")
  fmt.Println("Working directory set to:", p4.Cwd())

• Cwd() -> string

  Retrieves the current working directory.

  Copy

  fmt.Println("Current working directory:", p4.Cwd())

• SetClient(client string)

  Sets the client workspace name.

  Copy

  p4.SetClient("my_client")
  fmt.Println("Client workspace set to:", p4.Client())

• Client() -> string

  Retrieves the current client workspace name.

  Copy

  fmt.Println("Current client workspace:", p4.Client())

• SetUser(user string)

  Sets the username for the Perforce client.

  Copy

  p4.SetUser("username")
  fmt.Println("User set to:", p4.User())

• User() -> string

  Retrieves the current username.

  Copy

  fmt.Println("Current user:", p4.User())

• SetPassword(password string)

  Sets the password for the Perforce client.

  Copy

  p4.SetPassword("mypassword")
  fmt.Println("Password set.")

• Password() -> string

  Retrieves the current password.

  Copy

  fmt.Println("Current password:", p4.Password())

• SetPort(port string)

  Sets the P4 Server port.

  Copy

  p4.SetPort("perforce:1666")
  fmt.Println("Server port set to:", p4.Port())

• Port() -> string

  Retrieves the current P4 Server port.

  Copy

  fmt.Println("Current server port:", p4.Port())

• SetProg(prog string)

  Sets the program name for the Perforce client.

  Copy

  p4.SetProg("my_program")
  fmt.Println("Program name set to:", p4.Prog())

• Prog() -> string

  Retrieves the current program name.

  Copy

  fmt.Println("Current program name:", p4.Prog())

• SetTicketFile(ticketFile string)

  Sets the path to the Perforce tickets file.

  Copy

  p4.SetTicketFile("/path/to/tickets")
  fmt.Println("Ticket file set to:", p4.TicketFile())

• TicketFile() -> string

  Retrieves the path to the Perforce tickets file.

  Copy

  fmt.Println("Current ticket file path:", p4.TicketFile())

• SetTrustFile(trustFile string)

  Sets the path to the Perforce trust file.

  Copy

  p4.SetTrustFile("/path/to/trust")
  fmt.Println("Trust file set to:", p4.TrustFile())

• TrustFile() -> string

  Retrieves the path to the Perforce trust file.

  Copy

  fmt.Println("Current trust file path:", p4.TrustFile())

• SetVar(variable string, value string)

  Sets a Perforce variable.

  Copy

  p4.SetVar("P4DEBUG", "1")
  fmt.Println("P4DEBUG set.")

• SetProtocol(protocol string, value string)

  Sets a Perforce protocol variable.

  Copy

  p4.SetProtocol("api", "80")
  fmt.Println("Protocol set.")

• Version() -> string

  Retrieves the Perforce client version.This method is used to get the version of the Perforce client API being used, which can be helpful for debugging or compatibility checks.

  Copy

  version := p4.Version()
  fmt.Println("Client Version:", version)

• SetVersion(version string)

  Sets the Perforce client version.
  This method is used to specify the version of the client API, which can be useful for compatibility with specific server versions.

  Copy

  p4.SetVersion("2023.1")
  fmt.Println("Client version set to:", p4.Version())

• SetHost(host string)

  Sets the hostname for the Perforce client. This is used to identify the client machine to the P4 Server.

  Copy

  p4.SetHost("my-hostname")
  fmt.Println("Host set to:", p4.Host())

• Host() string

  Retrieves the hostname of the Perforce client.

  Copy

  host := p4.Host()
  fmt.Println("Current Host:", host)

• SetIgnoreFile(ignoreFile string)

  Sets the path to the ignore file for the Perforce client. The ignore file specifies files or directories to exclude from version control.

  Copy

  p4.SetIgnoreFile(".p4ignore")
  fmt.Println("Ignore file set to:", p4.IgnoreFile())

• IgnoreFile() string

  Retrieves the path to the ignore file used by the Perforce client.

  Copy

  ignoreFile := p4.IgnoreFile()
  fmt.Println("Current Ignore File:", ignoreFile)

• Ignored(path string) bool

  Checks if a specified file or directory is ignored based on the ignore file.

  Copy

  isIgnored := p4.Ignored("temp.txt")
  if isIgnored {
      fmt.Println("File temp.txt is ignored.")
  } else {
      fmt.Println("File temp.txt is not ignored.")
  }

• SetLanguage(language string)

  Sets the language for the Perforce client. This is used for localization and internationalization.

  Copy

  p4.SetLanguage("en")
  fmt.Println("Language set to:", p4.Language())

• Language() string

  Retrieves the current language setting of the Perforce client.

  Copy

  language := p4.Language()
  fmt.Println("Current Language:", language)

• GetP4ConfigFile() string

  Retrieves the path to the Perforce configuration file (P4CONFIG) used by the client.

  Copy

  configFile := p4.GetP4ConfigFile()
  fmt.Println("P4 Config File:", configFile)

• ApiLevel() int

  Retrieves the API level of the Perforce client. The API level determines the features and behaviors supported by the client.

  Copy

  apiLevel := p4.ApiLevel()
  fmt.Println("Current API Level:", apiLevel)

• SetApiLevel(apiLevel int)

  Sets the API level for the Perforce client. This is useful for enabling or disabling specific features based on the API version.

  Copy

  p4.SetApiLevel(80)
  fmt.Println("API Level set to 80.")

• Streams() bool

  Checks if streams are enabled for the Perforce client. Streams are a feature for managing branching and merging workflows.

  Copy

  if p4.Streams() {
      fmt.Println("Streams are enabled.")
  } else {
      fmt.Println("Streams are not enabled.")
  }

• SetStreams(enableStreams bool)

  Enables or disables streams for the Perforce client.

  Copy

  p4.SetStreams(true)
  fmt.Println("Streams enabled.")

• Tagged() bool

  Checks if tagged output is enabled for the Perforce client. Tagged output provides structured data for easier parsing.

  Copy

  if p4.Tagged() {
      fmt.Println("Tagged output is enabled.")
  } else {
      fmt.Println("Tagged output is not enabled.")
  }

• SetTagged(enableTagged bool)

  Enables or disables tagged output for the Perforce client.

  Copy

  p4.SetTagged(true)
  fmt.Println("Tagged output enabled.")

• Track() bool

  Checks if tracking is enabled for the Perforce client. Tracking provides additional information about command execution.

  Copy

  if p4.Track() {
      fmt.Println("Tracking is enabled.")
  } else {
      fmt.Println("Tracking is not enabled.")
  }

• SetTrack(enableTrack bool)

  Enables or disables performance tracking for thePerforce client. This setting must be configured before establishing a connection to the client. By default, tracking is disabled (false).

  Copy

  result, err := p4.SetTrack(true)
  if err != nil {
      fmt.Println("Error in setting track:", err)
  }
  fmt.Println("Tracking enabled.")

• Graph() bool

  Checks if graph depot support is enabled for the Perforce client. Graph depots are used for managing Git repositories in Perforce.

  Copy

  if p4.Graph() {
      fmt.Println("Graph depot support is enabled.")
  } else {
      fmt.Println("Graph depot support is not enabled.")
  }

• SetGraph(enableGraph bool)

  Enables or disables graph depot support for the Perforce client.

  Copy

  p4.SetGraph(true)
  fmt.Println("Graph depot support enabled.")

• Debug() int

  Retrieves the current debug level for the Perforce client. The debug level controls the verbosity of debug output.

  Copy

  debugLevel := p4.Debug()
  fmt.Println("Current Debug Level:", debugLevel)

• SetDebug(debugLevel int)

  Sets the debug level for the Perforce client.

  Copy

  p4.SetDebug(2)
  fmt.Println("Debug level set to 2.")

• MaxResults() int

  Retrieves the maximum number of results that the Perforce client will return for a command.

  Copy

  maxResults := p4.MaxResults()
  fmt.Println("Max Results:", maxResults)

• SetResults(maxResults int)

  Sets the maximum number of results that the Perforce client will return for a command.

  Copy

  p4.SetResults(1000)
  fmt.Println("Max Results set to 1000.")

• MaxScanRows() int

  Retrieves the maximum number of rows that the Perforce client will scan for a command.

  Copy

  maxScanRows := p4.MaxScanRows()
  fmt.Println("Max Scan Rows:", maxScanRows)

• SetMaxScanRows(maxScanRows int)

  Sets the maximum number of rows that the Perforce client will scan for a command.

  Copy

  p4.SetMaxScanRows(5000)
  fmt.Println("Max Scan Rows set to 5000.")

• MaxLockTime() int

  Retrieves the maximum lock time (in milliseconds) for a command executed by the Perforce client.

  Copy

  maxLockTime := p4.MaxLockTime()
  fmt.Println("Max Lock Time:", maxLockTime, "ms")

• SetMaxLockTime(maxLockTime int)

  Sets the maximum lock time (in milliseconds) for a command executed by the Perforce client.

  Copy

  p4.SetMaxLockTime(10000)
  fmt.Println("Max Lock Time set to 10000 ms.")

Handlers

• SetProgress(progress P4Progress)

  Sets a progress handler for the Perforce client. The progress handler is used to track the progress of long-running commands, such as sync or submit. The handler implements the P4Progress interface, which provides methods to monitor progress updates.

  Copy

  progressHandler := &MyProgressHandler{}
  p4.SetProgress(progressHandler)
  p4.Run("sync", "//...")

• SetHandler(handler P4OutputHandler)

  Sets an output handler for the Perforce client. The output handler is used to process the output of Perforce commands, such as text, binary data, or structured dictionaries. The handler implements the P4OutputHandler interface.

  Copy

  outputHandler := &MyOutputHandler{}
  p4.SetHandler(outputHandler)
  p4.Run("files", "//...")

• SetSSOHandler(handler P4SSOHandler)

  Sets a single sign-on (SSO) handler for the Perforce client. The SSO handler is used to manage authentication when SSO is enabled on the P4 Server. The handler implements the P4SSOHandler interface.

  Copy

  ssoHandler := &MySSOHandler{}
  p4.SetSSOHandler(ssoHandler)
  p4.Run("login")

• SetResolveHandler(handler P4ResolveHandler)

  Sets a resolve handler for the Perforce client. The resolve handler is used to manage file conflict resolution during operations like merge or integrate. The handler implements the P4ResolveHandler interface.

  Copy

  resolveHandler := &MyResolveHandler{}
  p4.SetResolveHandler(resolveHandler)
  p4.Run("resolve")