Helix Core is now P4. Product user interfaces will be updated soon. Learn more >>

P4 CLI Reference | 2025.1

# p4 submit

Submit a pending changelist and the files it contains to the depot, and/or submit an open stream spec.

## Syntax

    p4 [g-opts] submit [-r -s] [-f submitoption] -K [-b | --noretransfer 0|1]
                       [--parallel=threads=N[,batch=N][,min=N]]
    p4 [g-opts] submit [-r -s] [-f submitoption -K -b]
                       [--parallel=threads=N[,batch=N][,min=N]] file
    p4 [g-opts] submit [-r] [-f submitoption -K -b] [-So] -d description
                       [--parallel=threads=N[,batch=N][,min=N]]
    p4 [g-opts] submit [-r] [-f submitoption -K -b] [-Sx] -d description
                       [--parallel=threads=N[,batch=N][,min=N]] file
    p4 [g-opts] submit [-r] [-f submitoption] -K [-b | --noretransfer 0|1] -c change
                       [--parallel=threads=N[,batch=N[,min=N]]]
    p4 [g-opts] submit -e shelvedchange -K [-b] [--parallel=threads=N[,batch=N][,min=N]]
    p4 [g-opts] submit -i [--parallel=threads=N[,batch=N][,min=N]]
    p4 [g-opts] submit [-r -s] [-f submitoption -K -b] [--parallel=threads=N[,batch=N][,min=N]]

Syntax conventions

## Description

When a file has been opened by `p4 add`, `p4 edit`, `p4 delete`, or `p4 integrate`, the file is listed in a `changelist`. The user’s changes to the file are made only within the client workspace copy until the changelist is sent to the depot with `p4 submit`.

In addition to the files being submitted, any open stream specification is also submitted. To submit only files and not an open stream spec, see streams and p4 submit. To learn more about open stream specifications, see `p4 stream`.

By default, files are opened within the default changelist, but you can also create new numbered changelists with `p4 change`.

- To submit the default changelist, use `p4 submit`.

- To submit a numbered changelist, use `p4 submit -c changelist`.

  Using the `-c` option also allows you to change the description information for a numbered changelist.

By default, all files in the changelist are submitted to the depot, and files open for `edit`, `add`, and `branch` are closed when submitted, whether there are any changes to the files or not. To change this default behavior, set the `SubmitOptions` field in the `p4 client` form for your workspace.

To override your workspace’s `SubmitOptions:` setting from the command line, use:

`p4 submit -f submitoption`.

When used with the default changelist, `p4 submit` brings up a form for editing in the editor defined by the `EDITOR` (or `P4EDITOR`) environment variable. Files can be deleted from the changelist by deleting them from the form, but these files will remain open in the next default changelist. To close a file and remove it from all changelists, use `p4 revert`.

All changelists have a `Status` field. The value of this field is `pending` or `submitted`:

- Submitted changelists have been successfully submitted with `p4 submit`.
- Pending changelists have been created by the user but not yet been submitted successfully.

To supply a changelist description from the command line, use the `-d` option. No change description dialog is presented. The `-d` option works only with the default changelist, not with numbered changelists.

A file’s location in the depot is determined by its location in the local filesystem and by the client workspace definition, which is specified in the `p4 client` form. See the "Configure clients" chapter in the P4 CLI Documentation.

For perfomance reasons, the submit operation updates the `maxCommitChange` counter prior to completing the computation of the size of `text+k` files, which are stored as type `text` with keyword expansion. To learn about `maxCommitChange`, see p4 counters.

### Submit processing

p4 submit works atomically: either all the files listed in the changelist are saved in the depot, or none of them are. The atomic nature of `p4 submit` allows files to be grouped in a changelists according to their purpose. For example, a single changelist might contain changes to three files that fix a single bug. `p4 submit` fails if it is interrupted, or if any of the files in the changelist are not found in the current client workspace, are locked in another client workspace (with `p4 lock`), or require resolution and remain unresolved.

A progress indicator is available for `p4 submit` if you request it with `p4 -I submit`.

Before committing a changelist, `p4 submit` briefly locks all files being submitted. If any file cannot be locked or submitted, the files are left open in a numbered pending changelist. By default, the files in a failed submit operation are left locked unless the `submit.unlocklocked` configurable is set. If `submit.unlocklocked` is set, files are unlocked even if they were manually locked prior to submit if submit fails.

If `p4 submit` fails while processing the default changelist, the changelist is assigned the next number in the changelist sequence, and the default changelist is emptied. The changelist that failed submission must be resubmitted by number after the problems are fixed.

If `p4 submit` fails, some or all of the files might have been copied to the server. By default, retrying a failed submit transfers all these files again unless the `submit.noretransfer` configurable is set, in which case the server attempts to detect if the files have already been transferred and does not re-transfer all files when retrying a failed submit. You can use the `--noretransfer` option to override the `submit.noretransfer` configurable and allow the user to choose the preferred re-transfer behavior for the current submit operation.

### Parallel submits

All parallel processing on the server is regulated using the `net.parallel.max` configurable:

- To disable parallel processing, set to 0 or 1

- To enable parallel processing and specify the maximum number of concurrent threads for a single p4 submit, p4 sync, or p4 shelve command, set a value between 2 and 100. Configuration or command line options that request a greater number of parallel threads than the value of net.parallel.max remain limited to the net.parallel.max value.

Too many threads can degrade performance.

For submits, you can transfer files in parallel. If there are sufficient resources, a submit command might execute more rapidly by transferring multiple files in parallel. For this feature to work, you must have both server and client upgraded to version 2015.2 or later.

#### Manual parallel submit

To enable parallel submits, set the net.parallel.max configurable to a value greater than `1`. (See also Automatic parallel submits.)

- Specify `threads=`N`` to request that files be sent concurrently using the specified number of independent network connections. The threads grab work in batches.

- Specify `batch=`N`` to control the number of files in a batch.

- Specify the `min` option to control the minimum number of files necessary for a parallel submit operation to occur.

If the `net.parallel.max` configuration variable is not set, the command executes without using parallel threads.

If the requested number of parallel threads exceeds the value set for `net.parallel.max`, the command uses the maximum number of allowed threads.

Parallel submits from an edge server to a commit server use standard pull threads to transfer the files. To ensure that pull threads can be run on the commit server:

- Ensure that the service user used by the commit server is logged into the edge server.

- Ensure that the `ExternalAddress` field of the edge server’s server spec is set to the address used by the commit server’s pull threads to connect to the edge server.

If the commit and edge servers communicate on a network separate from the network used by clients to communicate with the edge server:

- The `ExternalAddress` field must specify the edge server IP address and port number for connections from the commit server.

- The edge server must listen on the two (or more) networks.

Parallel submit is not supported from an edge server if the commit server is on a Windows platform. In this case, --parallel or automatic parallel processing for submit is silently ignored, and the submit run without using parallel threads.

#### Automatic parallel submits

To enable automatic parallel processing for `p4 submit`, set non-zero values for both configurables: net.parallel.max and net.parallel.submit.threads. For example:

`p4 configure set net.parallel.max=8`

`p4 configure set net.parallel.submit.threads=3`

If automatic parallel processing is enabled, the following configurables no longer have the default value of `0`:

Configurable | New value | For p4 submit
--- | --- | ---
net.parallel.submit.batch | 8 | The number of files in a batch
net.parallel.submit.min | 9 | The mininum number of files in a batch

In this case, you can use any of the syntax variants for the `p4 submit` command without specifying the `--parallel` option and processing will be automatically done in parallel.

- If you do use the `--parallel` option explicitly and you have the `net.parallel.*` configurables set, the configurable values you specify on the command line override the value of the configurables.
- You can turn off automatic parallel submit by unsetting the `net.parallel.submit.threads` configurable.
- You can disable the parallel submit configurable settings by specifying `p4 submit --parallel=0`.

### Performance and parallel submits

Using parallel submits improves performance in cases like the following:

- Significant network latency exists somewhere along the path through which the submitted file content travels from the client to the repository where the file content is stored.

  This includes significant network latency between a Proxy and Server, or between an edge server and a commit server. When using parallel submit in such a configuration, the inherent TCP delays related to network latency occur concurrently, rather than sequentially when not using parallel submit.

- Significant resources are required during the transfer of the submitted file, and those resources are available.

  For example, if significant CPU cycles are required to compress ctext or binary file content as it is transferred from a client to a server, the compression of the file content can occur on one CPU core per parallel submit thread compressing either a ctext or binary file, so long as there are enough available CPU cores.

In other cases, using parallel submit might not result in significant performance benefits:

- In some environments, network bandwidth can be a precious resource.

  If network latency is minimal, it might not take many parallel submit threads to use the available network bandwidth. Once the available network bandwidth is used, adding parallel submit threads might not improve performance. This is especially true when transferring file content for which only network bandwidth resources are needed, such as when transferring ubinary files.

- Using a small value for the `batch` and `min` arguments specified with the `--parallel` option is only practical in some cases.

  For example, if a small number of large ctext or binary files are submitted using parallel submit, transferring a small number of files per parallel submit thread can result in the best performance, provided that adequate CPU and network bandwidth resources are available. For parallel submit to transfer an evenly-distributed number of files over the number of parallel submit threads specified (which defaults to `4`), the `batch` argument might need to be set to a value lower than its default of `8`.

  - For example, if submitting eight large ctext or binary files using four parallel submit threads, the `batch` argument should be set to two. The value for the `min` argument, which defaults to `9`, should be set to less than or equal to the number of large ctext or binary files being submitted.

  - On the other hand, using a small value for the `batch` argument can degrade performance when submitting many small files using parallel submit. In such a case, the overhead of the server frequently querying the `db.sendq` table for each batch by each parallel submit thread can result in `db.sendq` concurrency issues.

To learn more, see See Parallel processing for submits, syncs, and shelves in the P4 Server Administration Documentation.

### About background archive transfer for edge server submits

This feature is designed to reduce the amount of wait time end-users perceive when submitting files.

The -b option of the p4 submit command can be used on an edge server to enable the edge archive to be transferred to the commit server in the background. The submit process on the Commit server schedules the transfers and completes the submit without the end user waiting for transfers to finish. The archives on the originating Edge server are transferred to the commit server by pull threads initiated by submit on the Commit server.

Submitting pending (not shelved) changes using the -b option causes any change-submit triggers to be fired before edge-content triggers. To learn more, see Triggers and commit-edge. An administrator must ensure that pull threads can be run on the Commit server. The Edge server IP address and port number used by the Commit server to connect to the Edge server must be specified in the ExternalAddress: field of the Edge server spec. To learn more, see Background archive transfer for edge server submits in the P4 Server Administration Documentation.

#### Limitations

- If the administrator has not enabled background submit, the -b option is ignored and standard submit behavior occurs.

- Archives of ktext files are transferred serially because archive content depends on commit server work.
- This feature does not support graph depots.

- Background archive transfer is incompatible with:

  - The command-line --noretransfer option.

  - The submit.noretransfer configurable.

### streams and p4 submit

By default, an open stream spec is submitted with the files.

When the default changelist is submitted, the `-So` and `-Sx` options control whether an open stream spec is included.

- To submit only the open stream spec, use `-So` with no file list.

- To exclude the open stream spec when submitting some of the files, use `-Sx` with a file list.

- To exclude the open stream spec when submitting all of the files, use `-Sx` with no file list.

To learn more, see Examples for submitting streams.

### Performance for large binary files

You might be able to boost performance for the p4 submit command. To learn more, see Delta Transfer of large binary files in the P4 Server Administration Documentation.

## Form Fields

Field Name | Type | Description
--- | --- | ---
`Change:` | Read-only | The change number, or `new` if submitting the default changelist.
`Client:` | Read-only | Name of current client workspace.
`User:` | Read-only | Name of current P4 Server user.
`Status:` | Read-only, value | One of `pending`, `submitted`, or `new`. Not editable by the user. The status is: new when the changelist is created. pending when it has been created but has not yet been submitted to the depot with `p4 submit`. submitted when its contents have been stored in the depot with `p4 submit`.
`Description:` | Writable | Textual description of changelist. This value must be changed.
`Jobs:` | List | A list of jobs that are fixed by this changelist. This field does not appear if there are no relevant jobs. Any job that meets the jobview criteria as specified on the `p4 user` form are listed here by default, but can be deleted from this list.
`Type:` | Writable, value | Type of change: `restricted` or `public`. A restricted shelved or committed changelist denies access to users who do not own the changelist and who do not have list The list of file revisions most recently synced from the depot into the workspace. In other words, the list of files that the client workspace has. permission to at least one file in the changelist. A restricted pending (unshelved) changelist denies access to non-owners of the changelist. Public changes are displayed without these restrictions.
`Files:` | List | A list of files being submitted in this changelist. Files can be deleted from this list, but cannot be changed or added.

## Options for files

-b | See the section above, "About background archive transfer for edge server submits".
`-c change` | Submit changelist number `change`. Changelists are assigned numbers either manually by the user with `p4 change`, or automatically by P4 Server when submission of the default changelist fails.
`-d description` | Immediately submit the default changelist (and the stream, if open) with the `description` supplied on the command line, and bypass the interactive form. This option is useful when scripting, but does not allow for jobs to be added, nor for the default changelist to be modified.
`-e shelvedchange` | Submit shelved changelist number `shelvedchange`. The `-e` option submits a shelved changelist without transferring files or modifying the workspace. The shelved change must be owned by the person submitting the change, but the workspace can be different. Files shelved to a stream target can only be submitted by a stream workspace that is mapped to the target stream. In addition, files shelved to a non-stream target cannot be submitted by a stream workspace. To submit a shelved change, all files in the shelved change must be up-to-date and resolved. No files can be open in any workspace at the same change number. The `p4 client` form’s `SubmitOptions:` settings (such as `revertunchanged`) are ignored. If the submit is successful, the shelved change and files are no longer available to be unshelved or submitted. This is the only submit option supported for files with propagating attributes from an edge server in a multi-server environment.
`-f submitoption` | Override the `SubmitOptions:` setting in the `p4 client` form. Valid `submitoption` values are: `submitunchanged` All open files (with or without changes) are submitted to the depot. This is the default behavior of P4 Server. `submitunchanged+reopen` All open files (with or without changes) are submitted to the depot, and all files are automatically reopened in the default changelist. `revertunchanged` Only those files with content or type changes are submitted to the depot. Unchanged files are reverted. For DVCS, revertunchanged is the default. `revertunchanged+reopen` Only those files with content or type changes are submitted to the depot and reopened in the default changelist. Unchanged files are reverted and not reopened in the default changelist. Because the two `revertunchanged` options do not revert a file to the state where the have revision was obtained, you must run `p4 sync -f` to revert the file to the state where the have revision was obtained. `leaveunchanged` Only those files with content or type changes are submitted to the depot. Any unchanged files are moved to the default changelist. `leaveunchanged+reopen` Only those files with content or type changes are submitted to the depot. Unchanged files are moved to the default changelist, and changed files are reopened in the default changelist. This option is similar to `submitunchanged+reopen`, except that no unchanged files are submitted to the depot.
`-K` | Suppress keyword expansion when updating `+k` type files on the client. See File type modifiers.
`-i` | Read a changelist specification from standard input. Input must be in the same format as that used by the `p4 submit` form.
`--noretransfer 0|1` | Set to 1 to have the server avoid re-transferring files that have already been archived after a failed submit operation. Set to 0 to have the server retransfer all files after a failed submit operation. This setting overrides the setting of the `submit.noretransfer` configurable for the current submit operation.
`--parallel` | Specify options for parallel file transfer. The configurable `net.parallel.max` must be set to a value greater than `1` to enable the `--parallel` option. threads=`n` sends files concurrently using `n` independent network connections. The specified number of threads grab work in batches. batch=`n` suboption specifies the number of files in a batch. min=`n` suboption specifies the minimum number of files in a parallel sync. A sync with fewer files does not initiate parallel file transfers. See Parallel syncs .
`-r` | Reopen files for `edit` in the default changelist after submission. Files opened for `add` or `edit` in will remain open after the submit has completed.
`-s` | Allows jobs to be assigned arbitrary status values on submission of the changelist, rather than the default status of `closed`. To leave a job unchanged, use the special status of `same`. On new changelists, the fix status is displayed as the special status `ignore`. (If the status is left unchanged, the job is not fixed by the submission of the changelist.) This option works in conjunction with the `-s` option to `p4 fix`, and is intended for use in conjunction with defect tracking systems.
`file` | A single parameter that can be a path with '…​' as a wildcard. This file pattern parameter can only be used when submitting the default changelist. The files in the default changelist that match the specified pattern are submitted. Files that don’t match the file pattern are moved to the next default changelist.
`g-opts` | See Global options.

## Options for streams

`-So` | Submit only the only stream spec. No list of files allowed.
`-Sx` | Excludes the open stream spec when submitting the specified list of files

## Usage Notes

Can File Arguments Use Revision Specifier? | Can File Arguments Use Revision Range? | Minimal Access Level Required | Command Alias
--- | --- | --- | ---
No | No | `write` | If submit.autobgtransfer is set, `p4 submit` is an alias for `p4 submit -b`

## Examples for submitting streams

p4 submit | Submit the default changelist, including the current open stream spec.
p4 submit -c 4739 | Submit the numbered changelist, including the current open stream spec.
p4 submit -So | Submit only the open stream spec.
p4 submit -Sx | Submit the default changelist, but do not submit the open stream spec.
p4 submit foo bar p4 submit -Sx foo bar | Submit the specified changelist, but do not submit the open stream spec.

## Related commands

To create a new, numbered changelist | `p4 change`
To open a file in a client workspace and list it in a changelist | `p4 add` `p4 edit` `p4 delete` `p4 integrate`
To move a file from one changelist to another | `p4 reopen`
To remove a file from all changelists, reverting it to its previous state | `p4 revert`
To view a list of changelists that meet particular criteria | `p4 changes`
To read a full description of a particular changelist | `p4 describe`
To read files from the depot into the client workspace | `p4 sync`
To edit the mappings between files in the client workspace and files in the depot | `p4 client`

Your search for returned results