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

P4 CLI Reference | 2025.1

# p4 change

Create or edit a changelist specification.

## Syntax

    p4 [g-opts] change [-s] [-f | -u] [[-O|I] changelist]
    p4 [g-opts] change -d [-f -s -O] changelist
    p4 [g-opts] change -o [-s] [-f] [[-O|I] changelist ]
    p4 [g-opts] change -i [-s] [-f | -u]
    p4 [g-opts] change -t restricted | public [-U user] [-f|-u|-O|-I] changelist
    p4 [g-opts] change -U user [-t restricted | public] [-f] changelist
    p4 [g-opts] change -d -f --serverid=X changelist

Syntax conventions

## Description

When files are opened with `p4 add`, `p4 delete`, `p4 edit`, or `p4 integrate`, the files are listed in a changelist. Edits to the files are kept in the local client workspace until the changelist is sent to the depot with `p4 submit`. By default, files are opened within the default changelist, but multiple changelists can be created and edited with the `p4 change` command.

This command also works with openable stream specifications.

The command `p4 -Ztag change -o` displays, in addition to other information, the access time for shelved files. You can use this information to determine if a shelved file has been abandoned and needs to be removed.

To edit the description of a pending changelist, or to view the fields of a submitted changelist, use `p4 changechangelist`.

### Changelist number - pending versus submitted

A submitted changelist number is an integer that uniquely identifies a changelist. P4 Server assigns pending changelist numbers in sequence. However, P4 Server might renumber a changelist upon submission to ensure that the set of submitted changelist numbers increases with time. Submitted changelist numbers are ordinal (increasing), but not necessarily consecutive. For example, 103, 105, 108, 109.

p4 change brings up a form for editing or viewing in the editor defined by the environment variable `P4EDITOR`. When no arguments are provided, this command creates a numbered changelist. All files open in the default changelist are moved to the numbered changelist.

If `p4 submit` of the default changelist fails, a numbered changelist is created in its place. The changelist must be referred to by its changelist number from that point forward.

## Form Fields

Field Name | Type | Description
--- | --- | ---
`Change:` | Read-only | Contains the changelist number if editing an existing changelist, or `new` if creating a new changelist.
`Date:` | Read-only | Date the changelist was last modified.
`Client:` | Read-only | Name of current client workspace.
`User:` | Read-only | Name of the user that is the change owner. The owner of a pending changelist without any files in it can transfer ownership of the changelist to another existing user. The transfer occurs by editing this field or by using the `-U user` option. The specified owner does not have to be a P4 Server 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.
`Status:` | Read-only | pending, `shelved`, `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`, `shelved` when its contents are shelved with `p4 shelve`, and `submitted` when its contents have been stored in the depot with `p4 submit`.
`Type:` | Writable, optional | Type of change: `restricted` or `public`. The `Type` field can be used to hide the change or its description from users. A `shelved` or `committed` change (as denoted in the `Status` field) that is `restricted` is accessible only to users who own the change or have `list` permission to at least one file in the change. Public changes are displayed without restrictions. By default, changelists are `public`. A P4 Server superuser can set the default changelist type (for changelists created after the configurable is set) by setting the `defaultChangeType` configurable.
`Description:` | Writable, mandatory | Textual description of changelist. This value must be changed before submission. If you do not have access to a restricted changelist, the description is replaced with a "no permission" message.
`ImportedBy:` | Read-only | Displays the name of the user who ran the `p4 fetch`, `p4 push`, or `p4 unzip` command that imported this change into the server. This field is primarily useful for distributed versioning (DVCS) scenarios, in which changelists are copied from one server to another, and help you correlate the changelist’s basic identity as it is copied. In such configurations, Perforce recommends using the `submit.identity` configurable to enable automatic generation of changelist identities by the `p4 submit`.
`Identity:` | Writable, mandatory | Contains a label which uniquely identifies this changelist across all servers where it has been fetched, pushed, or unzipped. This field is primarily useful for distributed versioning (DVCS) scenarios, in which changelists are copied from one server to another, and help you correlate the changelist’s basic identity as it is copied. In such configurations, use the `submit.identity` configurable to enable automatic generation of changelist identities by the `p4 submit`.
`Jobs:` | List | A list of jobs that are fixed by this changelist. The list of jobs that appears when the form is first displayed is controlled by the `p4 user` form’s `JobView:` setting. Jobs can be deleted from or added to this list.
Stream: | Writable, optional | This field can indicate one stream spec or be blank. Which opened stream spec, if any, to add to, or remove from, this changelist. To add a stream spec to the changelist, the stream spec must already be opened to the current client workspace.
`Files:` | List | The list of files being submitted in this changelist. Files can be deleted from this list, and files that are found in the default changelist can be added.

If there is a line under a field, indent that line. For example,

    Description:
        Created by maria

## Options

`-d` | Delete the changelist. This is usually allowed only with pending changelists that contain no files or pending fixes, but the superuser can delete changelists under other circumstances with the addition of the `-f` option. If you try to forcibly delete a changelist whose client is bound to another server, you need to specify the `--serverid` option and specify the server id of the other server. This ensures that you do not accidentally delete the changelist believing it to be on your own server.
`-u` | Update a submitted changelist. Only the `Jobs:`, `Description:`, or `Type` fields can be updated, and only the submitter of the changelist can update the changelist. The `-u` and the `-f` options are mutually exclusive.
`-f` | Force option. Allows the description, modification date, or user of a submitted changelist to be edited. Editing a submitted changelist requires `admin` or `super` access. Superusers and administrators can also overwrite read-only fields when using the `-f` option. The `-u` and the `-f` options are mutually exclusive.
`-f -d` | Forcibly delete a previously submitted changelist. Only a P4 Server administrator or superuser can use this command, and the changelist must have had all of its files removed from the system with `p4 obliterate`. The `p4 change -d -f change` command can delete any changelist that is associated with a stream, even the changelist that was created because the stream was deleted. This command can be run after the deletion or obliteratoin of the stream. See p4 stream for the `-d` and `--obliterate` options.
`-i` | Read a changelist specification from standard input. Input must be in the same format used by the `p4 change` form.
`-o` | Write a changelist specification to standard output.
`-O` | If a changelist was renumbered on submit, and you know only the original changelist number, use `-O` and the original changelist number to view or edit the changelist.
`-I` | Specifies that the changelist number is the Identity field of a changelist.
`-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.
`--serverid=`X`` | If you try to forcibly delete a changelist whose client is bound to another server, you need to specify the `--serverid` option and to specify the server id of the other server. This ensures that you do not accidentally delete the changelist, believing it to be on your own server. This variant of the `p4 change` command must be issued directly to the commit server.
`-t type` | Change a submitted changelist’s type to either `restricted` or `public`.
`-U user` | The `-U` user option changes the owner of an empty pending changelist. To reassign a changelist, you must either already be the changelist’s owner, or a user with `admin` permissions and use the `-f` option. (Unlike manually editing the `User` field in the `p4 change` form, this option is much more convenient for use within a trigger or script.)
`g-opts` | See Global options.

## Usage notes

Can File Arguments Use Revision Specifier? | Can File Arguments Use Revision Range? | Minimal Access Level Required | Command Alias
--- | --- | --- | ---
N/A | N/A | open, or `list` to use the `-o` option, or `admin` to use the `-f` option | `p4 changelist`

- You should create multiple changelists when editing files corresponding to different logical tasks. For example, if edits to files `file1.c` and `file2.c` fix a particular bug, and edits to file `other.c` add a new feature, `file1.c` and `file2.c` should be opened in one changelist, and `other.c` should be opened in a different changelist.
- p4 change changelist edits the specification of an existing changelist, but does not display the files or jobs that are linked to the changelist. Use `p4 opened` -c `changelist` to see a list of files linked to a particular changelist and `p4 fixes` `-c` `changelist` to see a list of jobs linked to a particular changelist.
- To move a file from one changelist to another, use `p4 reopen`, or use `p4 revert` to remove a file from all pending changelists.

## Examples

`p4 change` | Create a new changelist.
`p4 change -f 25` | Edit previously submitted changelist 25. Must have `admin` or `super` access level.
`p4 change -d 29` | Delete changelist 29. This succeeds only if changelist 29 is `pending` and contains no files.
p4 change -f -d 121 | Force the deletion of the specified changelist

## Related commands

To submit a changelist to the depot | `p4 submit`
To move a file from one changelist to another | `p4 reopen`
To remove a file from all pending changelists | `p4 revert`
To list changelists meeting particular criteria | `p4 changes`
To list opened files | `p4 opened`
To list fixes linked to particular changelists | `p4 fixes`
To link a job to a particular changelist | `p4 fix`
To remove a job from a particular changelist | `p4 fix` `-d`
To list all the files in a changelist | `p4 opened` `-c` `changelist`
To get a description of files changed in a changelist | `p4 describe` `changelist`

Your search for returned results