p4 submit
Synopsis
Commit a pending changelist and the files it contains to the depot.
Syntax
p4 [g-opts
] submit [-r -s] [-f
submitoption
] [--noretransfer
0|1]
p4 [g-opts
] submit [-r -s] [-f
submitoption
] file
p4 [g-opts
] submit [-r] [-f
submitoption
] -d
description
p4 [g-opts
] submit [-r] [-f
submitoption
] -d
description
file
p4 [g-opts
] submit [-r] [-f
submitoption
] [--noretransfer 0|1] -c
change
p4 [g-opts
] submit -e
shelvedchange
p4 [g-opts
] submit -i [-r -s] [-f
submitoption
]
--parallel=threads=N
[,batch=N
][,min=N
]
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, run
p4 submit -aF
. For more information on 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 "Refining
Workspace Views" in the Helix Versioning Engine User Guide for more information.
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. Files are unlocked even if
they were manually locked prior to submit if submit fails when
submit.unlocklocked
is set.
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
You can transfer files in parallel during the submit process. 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.1 or newer. Please read this section in its entirety to make sure that you are using this feature appropriately.
To enable parallel submits, set the net.parallel.max
configurable.
-
Specify
threads=
to request that files be sent concurrently using the specified number of independent network connections. The threads grab work in batches. You specifyN
batch=
to control the number of files in a batch.N
A submit that is too small will not initiate parallel file transfers. Use the
min
option to control the minimum number of files in a parallel submit.If the
net.parallel.max
configuration variable is not set, or if the requested number of parallel threads exceeds the value set fornet.parallel.max
, the command will execute without using parallel threads or will use the maximum number of allowed threads. -
Parallel submits from an edge server to a commit server use standard pull threads to transfer the files. The administrator must ensure that pull threads can be run on the commit server by doing the following:
- Makes sure that the service user used by the commit server is logged into the edge server.
-
Make sure the
ExternalAddress
field of the edge server’s server spec is set to the address that will be 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 network that is used for connections from the commit server. Furthermore, the edge server must listen on the two (or more) networks.
-
The
--parallel
option is ignored when the archives are shared, forp4 submit -e
, and when progress indicators are used.You can set the
net.parallel.max
,net.parallel.submit.threads
,net.parallel.submit.min
, andnet.parallel.submit.batch
configurables to automate parallel processing. In this case, you can use any of the syntax variants for thep4 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 thenet.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
.
- If you do use the
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
andmin
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. In order for parallel submit to transfer an evenly-distributed number of files over the number of parallel submit threads specified (which defaults to four), the
batch
argument might need to be set to a value lower than its default of eight. (For example, if submitting eight large ctext or binary files using four parallel submit threads, thebatch
argument should be set to two.) And it follows that the value for themin
argument, which defaults to nine, 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. The overhead of the server frequently queryingdb.sendq
for each batch by each parallel submit thread can result indb.sendq
concurrency issues. This is because as the size of the files submitted using parallel submit decreases, the more frequently the server queriesdb.sendq
for the next batch processed by a parallel submit thread.
Form Fields
Field Name | Type | Description |
---|---|---|
|
Read-only |
The change number, or |
|
Read-only |
Name of current client workspace. |
|
Read-only |
Name of current Perforce user. |
|
Read-only, value |
One of The status is |
|
Writable |
Textual description of changelist. This value must be changed. |
|
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
|
|
Writable, value |
Type of change: A restricted shelved or committed changelist denies access to users who do not own the changelist and who do not have list 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. |
|
List |
A list of files being submitted in this changelist. Files can be deleted from this list, but cannot be changed or added. |
Options
|
Submit changelist number Changelists are assigned numbers either manually by the user with
|
|
Immediately submit the default changelist with the |
|
Submit shelved changelist number The To submit a shelved change, all files in the shelved change must be up
to date and resolved. No files may be open in any workspace at the same
change number. Your This is the only submit option supported for files with propagating attributes from an edge server in a distributed environment. |
|
Override the
|
|
Read a changelist specification from standard input. Input must be in
the same format as that used by the |
|
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
|
|
Specify options for parallel file transfer. The configuration variable
See Parallel processing for more information. |
|
Reopen files for |
|
Allows jobs to be assigned arbitrary status values on submission of
the changelist, rather than the default status of On new changelists, the fix status is displayed as the special status
This option works in conjunction with the |
|
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. |
|
See “Global Options”. |
Usage Notes
Can File Arguments Use Revision Specifier? | Can File Arguments Use Revision Range? | Minimal Access Level Required |
---|---|---|
No |
No |
|
Examples
|
Submit the default changelist. The user’s revisions of the files in this changelist are stored in the depot. |
|
Submit changelist 41. |
p4 submit *.txt |
Submit only those files in the default changelist that have a suffix
of |
p4 submit -d "header files" *.h |
Submit only those files in the default changelist that have a suffix
of |