by
The Apache Ant project currently provides a set of Perforce Tasks based on work by Les Hughes, Kirk Wylie, Matt Bishop and Antoine Levy-Lambert. We would like to acknowledge this work and thank the Apache Foundation and these dedicated developers for supporting Perforce users over the years. The P4Ant project is based on the P4Java API and as a result it is self-contained and does not require any third-party libraries or the Perforce command-line client. This integration supports many additional features including shelving and is distributed in both binary and source forms.
The P4Ant tasks implement Perforce commands using the Perforce Java API. These tasks are intended for build automation with Ant.
Note: The P4Ant tasks are known to work with P4Java 2010.1+ (Perforce Java API), JDK 1.5.0+ and Ant 1.7.0+.
| Task | Description |
| P4JAdd | Open new files to add to the depot. |
| P4JChange | Create or edit a changelist description. |
| P4JChanges | Display a list of pending and submitted changelists. |
| P4JCounter | Display, set, or delete a counter. |
| P4JDelete | Open an existing file to delete it from the depot. |
| P4JDiff2 | Display diff (server side) of two depot files on the server. |
| P4JEdit | Open existing files for edit. |
| P4JFiles | List files in the depot. |
| P4JFix | Mark jobs as being fixed by a changelist number. |
| P4JFstat | Dump file info in the depot without accessing their contents. |
| P4JGrep | Print lines in files that match a pattern. |
| P4JHave | List files and revisions that have been synced to the client workspace. |
| P4JIntegrate | Stage change propagation from source files to target files. |
| P4JJob | Create or edit a job specification. |
| P4JJobs | Display list of jobs. |
| P4JLabel | Create a new label specification or edit an existing label specification. |
| P4JLabelsync | Synchronize a label with the contents of the current client workspace. |
| P4JLock | Lock opened files against changelist submission. |
| P4JMove | Move files from one location to another. |
| P4JReopen | Move opened files between changelists or change the files' type. |
| P4JResolve | Resolve conflicts between file revisions. |
| P4JRevert | Discard changes from opened files. |
| P4JShelve | Store files from a pending changelist in the depot, without submitting them. |
| P4JSubmit | Commits a pending changelist of changes made to open files to the depot. |
| P4JSync | Synchronize files from the depot into the client workspace. |
| P4JTag | Tag files with a label. |
| P4JUnlock | Release the lock on a file but leave the file open. |
| P4JUnshelve | Restore shelved files from a pending change into the client workspace. |
P4Ant tasks require some basic properties. These settings are respectively retrieved through individual attributes, project-wide properties and environment variables.
| Property | Attribute | Environment Variable | Description | Required | Default |
| p4.port | port | P4PORT | Perforce server host and port number on which it listens. Example, myp4server:1666 | Yes | perforce:1666 |
| p4.user | user | P4USER | Perforce user name. | Yes | User name on the host machine. |
| p4.passwd | passwd | P4PASSWD | Perforce user password. | No | |
| p4.client | client | P4CLIENT | Perforce client workspace. | Yes | Name of host machine. |
| -- | files | -- | File and revision specifiers separated by space.
If the path contains whitespace, it must be double-quoted. Local syntax: /staff/user/usercws/file.c@userlabel Depot syntax: //depot/source/module/file.c#8 Depot syntax: //depot/source/module/... Client syntax: //usercws/file.c#have |
No | |
| -- | file | -- | Nested file and revision specifiers. | No | |
| -- | fileset | -- | Files found in a directory tree starting in a base directory and are matched by patterns. | No | |
| -- | fields | -- | Nested name-value pair fields for Perforce specifications, such as job spec. | No |
Additionally, the following are general attributes you can specify. Many of the above properties can also be set using the "globaloption" attribute below.
| Attribute | Description | Required | Default |
| failonerror | Specifies whether to stop the build (true|yes|on)
or keep going (false|no|off) if
an error is returned from Perforce. |
No | true |
| globaloption | Nested key-value pair global options for
Perforce server. Note: these global options will override the local
attributes. For example, <globaloption key="password"
value="myp4passwd" /> will override the local "passwd" attribute's
value. See the Constant Field Values of the "com.perforce.p4java.PropertyDefs" class for property keys. |
No |
Defining your own Perforce server protocol-specific and usage properties files. Note: please consult Perforce support for details.
| Attribute | Description | Required | Default |
| protocolpropertiesfile | Specifies the location of the Perforce server protocol-specific properties file. Note that these properties are potentially accessed for each command. | No | |
| usagepropertiesfile |
Specifies the location of the Perforce server usage properties file. Note that these properties are potentially accessed for each command. | No |
Environment Variables:
(UNIX csh)
setenv P4PORT myp4server:1666
(UNIX sh, bash, etc.)
P4USER=myp4user; export P4USER
Project Properties:
<property name="p4.client" value="myp4clientws"/>
Task Attributes:
<p4[command]
port="myp4server:1666"
user="myp4user"
client="myp4clientws"
.
.
.
/>
<p4[command] files="//depot/source/module/file.c#8">
<fileset dir="/staff/user/usercws" id="user.source.files">
<include name="**/*.java"/>
<exclude name="**/*.class"/>
</fileset>
<file path="//usercws/file.c#have"/>
<file path="//usercws/file2.c#3"/>
.
.
.
</p4[command]>
<p4[command] ">
<field name="Status" value="open"/>
<field name="Description" value="Java bug - JVM out of memory error."/>
.
.
.
</p4[command]>
Please refer to the Perforce Command Reference for more information regarding the Perforce commands.
Opens new files for adding to the depot. If the files exist on the client they are read to determine if they are text or binary. If the file type cannot be determined then it is assumed to be text.
| Attribute | Description | Required | Default | P4 Command |
| changelist | If given, the open files are associated with the specified pending changelist number; otherwise the open files are associated with the default changelist. | No | 0 (default) | p4 add -c |
| noupdate | If true, it lists what would be opened for add without actually changing any files or metadata. | No | false | p4 add -n |
| filetype | If null, it looks for a filetype using the name-to-type mapping table managed by 'p4 typemap'. It senses the filetype by examining the file's contents and execute permission bit. If non-null, the files are added as that filetype. | No | null | p4 add -t |
| usewildcards | If true, filenames that contain wildcards are permitted. Filenames added to the repository that contain these special wildcard characters '@', '#', '%' or '*' will have those characters formatted into ascii hexadecimal representation. The only way of referring to those files once added will be to use the formatted version, the local filesystem name will not be recognized. | No | false | p4 add -f |
Assigns a specific file type to a new file, overriding any
settings in the typemap table.
Note: The "port", "user", "passwd" and "client" task attributes
are set explicitly.
<p4jadd
port="myp4server:1666"
user="myp4user"
passwd="myp4passwd"
client="myp4clientws"
files="file.pdf"
filetype="binary"
/>
Opens all the files within the user's current directory for add,
and links these files to changelist "13".
Note: The "P4PORT", "P4USER", "P4PASSWD" and "P4CLIENT"
environment variables are preset by the user.
<p4jadd
files="*"
changelist="13"
/>
Opens all "*.c" files in the user's "~/src" directory for add; also opens the "README" file in the user's current working directory for add. These files are linked to the default changelist.
<p4jadd>
<file path="README"/>
<file path="~/src/*.c"/>
</p4jadd>
Create or edit a changelist description. With no argument, 'change' creates a new changelist. If a changelist number is given, 'change' edits an existing, pending changelist. The "deletependingchangelist" (-d flag) option discards a pending changelist, but only if it has no opened files and no pending fixes associated with it.
| Attribute | Description | Required | Default | P4 Command |
| description | Description of the changelist. | No | null | |
| deletependingchangelist | If true, the pending changelist will be deleted. | No | false | p4 change -d |
| changelist | The changelist to be modified or deleted. | No | ||
| property | The property to be set with the changelist number. | No | p4.changelist |
Create a new changelist.
<p4jchange/>
Delete changelist "29". This succeeds only if changelist "29" is pending and contains no files.
<p4jchange
deletependingchangelist="true"
changelist="29"
/>
Display a list of pending and submitted changelists. If files are specified, it limits its report to changelists that affect those files. If the file specification includes a revision range, it limits its report to submitted changelists that affect those particular revisions.
| Attribute | Description | Required | Default | P4 Command |
| maxmostrecent | If positive, restrict the list to the specified number of most recent changelists. | No | 0 | p4 changes -m max |
| clientname | If non-null, restrict the results to changelists associated with the given client. | No | null | p4 changes -c client |
| username | If non-null, restrict the results to changelists associated with the given user name. | No | null | p4 changes -u user |
| includeintegrated | If true, also include any changelists integrated into the specified files (if any). | No | false | p4 changes -i |
| type | If not null, restrict output to pending, shelved or submitted changelists. | No | null | p4 changes -s status |
| longdesc | If true, produce a non-truncated long version of the description. | No | false | p4 changes -l |
| property | The property to be set with the list of the changelist numbers. | No | p4.changelists |
Show the last five submitted changelists that include any file under the project directory.
<p4jchanges
maxmostrecent="5"
files="//depot/project/..."
/>
Show the last five submitted changelists from client workspace "eds_elm".
<p4jchanges
maxmostrecent="5"
clientname="eds_elm"
/>
Show the last five submitted changelists from user "edk".
<p4jchanges
maxmostrecent="5"
username="edk"
/>
Show any changelists that include file file.c, as mapped to the depot through the client view, during the month of May 2000.
<p4jchanges
files="file.c@2000/05/01,2000/06/01"
/>
Display, set, or delete a counter. The first form displays the value of the named counter. The second form sets the counter to the given value. The third form deletes the counter. This usually has the same effect as setting the counter to 0.
| Attribute | Description | Required | Default | P4 Command |
| name | The name of the counter. | Yes | null | |
| value | The new value for the counter. | No | null | |
| delete | If true, the counter will be deleted. | No | false | p4 counter -d |
| perforcecounter | If true, this is a Perforce internal counter. | No | false | |
| property | The property to be set with the value of the counter. | No | p4.counter |
Set the value of a counter named "mycounter" to the value "123". If the "mycounter" counter does not exist, it is created. Requires review access.
<p4jcounter
name="mycounter"
value="123"
/>
Get the value of the "mycounter" counter and set it to the named "mycounter" property. If the "mycounter" counter does not exist, its value is displayed as 0. Requires list access.
<p4jcounter
name="mycounter"
property="p4.mycounter"
/>
Delete the "mycounter" counter.
<p4jcounter
delete="true"
name="mycounter"
/>
Opens files that currently exist in the depot for deletion. If the files are present on the client they are removed. If a pending changelist number is given the opened files are associated with that changelist, otherwise they are associated with the 'default' pending changelist.
| Attribute | Description | Required | Default | P4 Command |
| changelist | If positive, the deleted files are put into the pending changelist identified (this changelist must have been previously created for this to succeed). If zero or negative, the file is opened in the 'default' (unnumbered) changelist. | No | 0 (default) | p4 delete -c |
| noupdate | If true, don't actually do the deletes, just return the files that would have been opened for deletion. | No | false | p4 delete -n |
| deletenonsyncedfiles | If true, it allows deleting of files that are not synced into the client workspace. | No | false | p4 delete -v |
Opens the file called "README" in the depot's top level directory for deletion. The corresponding file within the client workspace is immediately deleted, but the file is not deleted from the depot until the default changelist is submitted.
<p4jdelete
files="README"
/>
Opens the "myfile" file in the current client workspace for deletion. The file is immediately removed from the client workspace, but won't be deleted from the depot until changelist "40" is sent to the server with the submit command.
<p4jdelete
changelist="40"
files="myfile"
/>
Run diff (on the server) of two files in the depot. Both files may optionally include a revision specification; the default is to compare the head revision. Wildcards may be used, but they must match between file1 and file2. Note if using clients or labels as file arguments they must be preceded with a file path e.g. //...@mylabel //...@yourlabel.
| Attribute | Description | Required | Default | P4 Command |
| file1 | The first depot file and revision specifier for diff2. | No | null | |
| file2 | The second depot file and revision specifier for diff2. | No | null | |
| branch | If not null, it causes diff2 to use the branch view to specify the pairs of files to compare. If file arguments are also present, they can further limit the files and specify the revisions for comparison. Note that if only one file is given, it restricts the right-hand side of the branch view. | No | null | p4 diff2 -b branch |
| quiet | If true, suppresses the display of the header lines of files whose content and types are identical and suppresses the actual diff for all files. | No | false | p4 diff2 -q |
| includenontextdiffs | If true, diff even files with non-text (binary) types. | No | false | p4 diff2 -t |
| gnudiffs | If true, use the GNU diff -u format and displays only files that differ. See the "-u" option in the main diff2 documentation for an explanation. | No | false | p4 diff2 -u |
| rcsdiffs | If true, use RCS diff. | No | false | p4 diff2 -dn |
| diffcontext | If positive, specifies the number of context diff lines; if zero, lets server pick context number; if negative, no options are generated. Corresponds to -dc[n], with -dc generated for diffcontext == 0, -dcn for diffcontext > 0, where "n" is of course the value of diffcontext. | No | -1 | p4 diff2 -dc[n] |
| summarydiff | If true, perform summary diff. | No | false | p4 diff2 -ds |
| unifieddiff | If positive, specifies the number of unified diff lines; if zero, lets server pick unified number; if negative, no options are generated. Corresponds to -du[n], with -du generated for unifieddiff == 0, -dun for unifieddiff > 0, where "n" is of course the value of unifieddiff. | No | -1 | p4 diff2 -du[n] |
| ignorewhitespacechanges | If true, ignore whitespace changes. | No | false | p4 diff2 -db |
| ignorewhitespace | If true, ignore whitespace. | No | false | p4 diff2 -dw |
| ignorelineendings | If true, ignore line endings. | No | false | p4 diff2 -dl |
Compare the second revision of file file to its head revision, and display a summary of what chunks were added to, deleted from, or changed within the file.
<p4jdiff2
file1="file#1"
file2="file"
summarydiff="true"
/>
Diff the revision of file that was in the depot after changelist "34" was submitted against the revision in the depot at midnight on December 4, 1998.
<p4jdiff2
file1="file@34"
file2="file@1998/12/04"
/>
Compare the head revisions of all files under the "//depot/rel1/..." path to the fourth revision of all files under the "//depot/rel2/..." path.
<p4jdiff2
file1="//depot/rel1/..."
file2="//depot/rel2/...#4"
/>
Not allowed. The wildcards in each file pattern must match.
<p4jdiff2
file1="/depot/rel1/*"
file2="//depot/rel2/..."
/>
Compare the second revision of the files under the "//depot/rel2/..." path to the files branched from it by branch mapping "branch2" at the revision they were at in changelist "50".
<p4jdiff2
branch="branch2"
file1="//depot/rel2/...#2"
file2="@50"
/>
Open existing files for edit. The server notes that the current user on the current client has the files opened, and then changes the file permission from read-only to read/write.
| Attribute | Description | Required | Default | P4 Command |
| noupdate | If true, it lists what would be opened for edit without actually changing any files or metadata. | No | false | p4 edit -n |
| bypassclientupdate | If true, bypasses the client file update. It can be used to tell the server that files in a client workspace are already editable, even if they are not present in the client view. Typically this flag is used to correct the Perforce server when it is wrong about the state of files on the client, use of this option can confuse the server if you are wrong about the client's contents. | No | false | p4 edit -k |
| changelist | If given, the file is put into the pending changelist; the changelist must have been previously created. Otherwise the file is opened in the 'default' (unnumbered) changelist. | No | 0 (default) | p4 edit -c |
| filetype | If non-null, the file is opened as that filetype. Otherwise, the filetype of the previous revision is reused. If the filetype given is a partial filetype, that partial filetype is combined with the previous revision's filetype. | No | null | p4 edit -t |
Opens all files ending in ".txt" within the current directory's doc subdirectory for edit. These files are linked to the default changelist; these files are stored as type text with keyword expansion.
<p4jedit
filetype="text+k1"
files="doc/*.txt"
/>
Implements pessimistic locking (exclusive-open) for all files in a depot. After this changelist is submitted, only one user at a time will be able to edit files in the depot named depotname.
<p4jedit
filetype="+l"
files="//depotname/..."
/>
Opens all files anywhere within the current working directory's file tree for edit. These files are examined to determine whether they are text or binary, and changes to these files are linked to changelist "14".
<p4jedit
files="..."
changelist="14"
/>
Open a file named "status@jan1.txt" for edit. Please see the Perforce command reference documentation for details about how to specify other characters reserved for use as Perforce wildcards.
<p4jedit
files="status%40jan1.txt"
/>
List files in the depot. List files named or matching wild card specification. Display shows depot file name, revision, file type, change action and changelist number of the current head revision. If client file names are given as arguments the view mapping is used to list the corresponding depot files.
If the file argument has a revision, then all files as of that revision are listed. If the file argument has a revision range, then only files selected by that revision range are listed, and the highest revision in the range is used for each file. Normally, the head revision is listed.
| Attribute | Description | Required | Default | P4 Command |
| allrevs | If true, displays all revisions within the specific range, rather than just the highest revision in the range. | No | false | p4 files -a |
Provides information about all files in the depot.
<p4jfiles
files="//depot/..."
/>
Provides information about all depot files visible through the client view.
<p4jfiles
files="//clientname/..."
/>
Provides information about all depot file revisions that existed on December 10, 2000.
<p4jfiles
files="@2000/12/10"
/>
Lists all files and revisions changed during business hours on March 31, 2001.
<p4jfiles
files="@2001/03/31:08:00,@2001/03/31:17:00"
/>
Lists files and revisions under the "//depot/proj2/..." path that are included in label "p2lab".
<p4jfiles
files="//depot/proj2/...@p2lab"
/>
Show information on the head revision of the "//depot/file.c" file. (that is, the highest revision in the implied range of "#1,#head").
<p4jfiles
files="//depot/file.c"
/>
Show information on every revision of the "//depot/file.c" file (that is, all revisions in the implied range of "#1,#head").
<p4jfiles
allrevs="true"
files="//depot/file.c"
/>
Mark jobs as being fixed by a changelist number. It marks each named job as being fixed by the changelist number given. The changelist may be either pending or, submitted and the jobs may still be opened or already closed (fixed by another changelist).
If the changelist has already been submitted and the job is still open then 'fix' marks the job closed. If the changelist has not been submitted and the job is still open, the job will be marked closed when the changelist is submitted. If the job is already closed, it is left alone.
| Attribute | Description | Required | Default | P4 Command |
| jobs | List of job IDs, separated by whitespace, for jobs that will have their status marked as "closed" or specified job status. | Yes | null | |
| changelist | Changelist number to be used for marking each named job as being fixed. Initialize to default changelist. | Yes | 0 (default) | p4 fix -c |
| status | If not null, use this as the new status rather than "closed". | No | null | p4 fix -s status |
| delete | If true, delete the specified fixes. | No | false | p4 fix -d |
Mark two jobs as being fixed by changelist "201". If changelist "201" is still pending, the jobs' status is changed to closed when the changelist is submitted.
<p4jfix
changelist="201"
jobs="job000141 job002034"
/>
Mark job "job002433" as suspended, rather than closed, when changelist "201" is submitted.
<p4jfix
changelist="201"
status="suspended"
jobs="job002433"
/>
Dumps information about each file, with each item of information on a separate line.
| Attribute | Description | Required | Default | P4 Command |
| filterstring | Limits the output to files satisfying the expression given. | No | null | p4 fstat -F filter |
| maxresults | If greater than 0, limits output to the first 'maxresults' number of files. | No | 0 | p4 fstat -m |
| reversesort | Sorts the output in reverse order. | No | false | p4 fstat -r |
| sincechangelist | Instructs fstat to display only files affected since the given changelist number. | No | -1 (unknown) | p4 fstat -c |
| affectedbychangelist | Instructs fstat to display only files affected by the given changelist number. | No | -1 (unknown) | p4 fstat -e |
| sortbyfiletype | Sort by filetype. | No | false | p4 fstat -St |
| sortbydate | Sort by date. | No | false | p4 fstat -Sd |
| sortbyheadrev | Sort by head revision. | No | false | p4 fstat -Sr |
| sortbyfilesize | Sort by file size. | No | false | p4 fstat -Ss |
| mappedfiles | Files mapped through the client view. | No | false | p4 fstat -Rc |
| syncedfiles | Files synced to the client. | No | false | p4 fstat -Rh |
| openednotheadrevfiles | Files opened not at the head revision. | No | false | p4 fstat -Rn |
| openedfiles | Files opened. | No | false | p4 fstat -Ro |
| openedresolvedfiles | Files opened that have been resolved. | No | false | p4 fstat -Rr |
| openedneedsresolvingfiles | Files opened that need resolving. | No | false | p4 fstat -Ru |
| shelvedfiles | Files shelved (requires 'affectedbychangelist'). | No | false | p4 fstat -Rs |
| allrevs | Output all revisions for the given files (this option suppresses other* and resolve* fields). | No | false | p4 fstat -Of |
| filesizedigest | Output a file size and digest field for each revision (this may be expensive to compute). | No | false | p4 fstat -Ol |
| bothpathtypes | Output the local file path in both Perforce syntax (//client/) as 'clientFile' and host form as 'path'. | No | false | p4 fstat -Op |
| pendingintegrationrecs | Output pending integration record information for files opened on the current client. | No | false | p4 fstat -Or |
| excludelocalpath | Exclude client-related data from output. | No | false | p4 fstat -Os |
Displays information on the "file.c" file.
<p4jfstat
files="file.c"
/>
Displays information on all ".c" files affected after the checking-in of files under changelist "20".
<p4jfstat
files="*.c"
mappedfiles="true"
sincechangelist="20"
/>
No client workspace information lines (i.e. "clientFile") are displayed.
<p4jfstat
files="*.c"
excludelocalpath="true"
/>
No client workspace information lines are displayed, but the file size and digest lines are displayed.
<p4jfstat
files="*.c"
excludelocalpath="true"
filesizedigest="true"
/>
Display information on all text files under the "//depot/main/..." path that are smaller than 1024 bytes in length.
<p4jfstat
files="//depot/main/..."
filterstring="fileSize < 1024 & headType=text"
filesizedigest="true"
/>
Grep searches files for lines matching a given regular expression; the expression (or pattern) can contain wildcards. The parser used internally is based on V8 regexp and might not be compatible with later parsers, however the majority of functionality is available.
If the file argument has a revision, then all files as of that revision are searched. If the file argument has a revision range, then only files selected by that revision range are listed, and the highest revision in the range is used for each file. Normally, the head revision is searched. See 'p4 help revisions' for help specifying revisions.
| Attribute | Description | Required | Default | P4 Command |
| pattern | The patterns used are regular expressions comparable to those used in UNIX. | Yes | null | p4 grep -e pattern |
| allrevisions | Search all revisions within the specified range, rather than only the highest revision in the range. | No | false | p4 grep -a |
| caseinsensitive | Perform case-insensitive pattern matching. (By default, matching is case-sensitive.). | No | false | p4 grep -i |
| includelinenumbers | Display a matching line number after the file revision number. | No | false | p4 grep -n |
| nonmatchinglines | Display files with non-matching lines. | No | false | p4 grep -v |
| searchbinaries | Treat binary files as text. (By default, only files of type text are selected for pattern matching.). | No | false | p4 grep -t |
| outputcontext | Display num lines of output context. If zero, option is off. | No | 0 | p4 grep -C num |
| trailingcontext | Display num lines of trailing context after matching lines. If zero, option is off. | No | 0 | p4 grep -A num |
| leadingcontext | Display num lines of trailing context before matching lines. If zero, option is off. | No | 0 | p4 grep -B num |
| fixedpattern | If true, interpret the pattern as a fixed string. If false, interpret the pattern as a regular expression. If true, corresponds to -F; if false, to -G. | No | false | p4 grep -F or -G |
Searches for files under the "//depot/java-project/..." path matching pattern "*Complex*Entity.java".
<p4jgrep
files="//depot/java-project/..."
pattern="*Complex*Entity.java"
/>
Searches for all files case-insensitive pattern matching "*baseball*.*".
<p4jgrep
files="//..."
caseinsensitive="true"
pattern="*baseball*.*"
/>
Searches for all files match a single character that is a letter, number, or underscore. Interpret the pattern as a regular expression.
<p4jgrep
files="//..."
fixedpattern="false"
pattern="[A-Za-z0-9_]"
/>
List files and revisions that have been synced to the client workspace. List revisions of named files that were last synced from the depot. If no file name is given list all files synced on this client.
| Attribute | Description | Required | Default | P4 Command |
Shows that the highest revision of the file has been copied to the client workspace.
<p4jhave
files="//depot/name"
/>
Shows that the fourth revision is the revision currently in the client workspace.
<p4jhave
files="//depot/name/...#4"
/>
Open files for branching or merging. 'integrate' stages change propagation from source files to target files, opening the target files in the client workspace. 'resolve' then merges content from the source files into the opened target files, and 'submit' commits the opened files to the depot. Integrations can be abandoned with 'revert'.
| Attribute | Description | Required | Default | P4 Command |
| fromfile | Source file and revision specifiers separated by space. If the path contains whitespace, it must be double-quoted. | Yes | null | |
| tofile | Target file and revision specifiers separated by space. If the path contains whitespace, it must be double-quoted. | Yes | null | |
| changelist | If positive, the integrated files are opened in the numbered pending changelist instead of the default changelist. | No | 0 (default) | p4 integrate -c |
| bidirectionalinteg | Causes the branch view to work bidirectionally, where the scope of the command is limited to integrations whose 'from' files match fromfile[revRange]. With the fromfile arg being specified in the main method fromfile parameter. | No | false | p4 integrate -b branch -s |
| integratearounddeletedrevs | If true, enable integrations around deleted revisions. | No | false | p4 integrate -d |
| rebranchsourceafterdelete | If the target file has been deleted and the source file has changed, will re-branch the source file on top of the target file. | No | null | p4 integrate -d -Dt |
| deletetargetafterdelete | If the source file has been deleted and the target file has changed, will delete the target file. | No | false | p4 integrate -d -Ds |
| integrateallafterreadd | If the source file has been deleted and re-added, will attempt to integrate all outstanding revisions of the file, including those revisions prior to the delete. Normally 'integrate' only considers revisions since the last add. | No | false | p4 integrate -d -Di |
| forceintegration | Forces integrate to act without regard for previous integration history. | No | false | p4 integrate -f |
| usehaverev | Causes the target files to be left at the revision currently on the client (the '#have' revision). | No | false | p4 integrate -h |
| dobaselessmerge | Enables integration between files that have no integration history. | No | false | p4 integrate -i |
| displaybasedetails | Display the base file name and revision which will be used in subsequent resolves if a resolve is needed. | No | false | p4 integrate -o |
| showactionsonly | Display what integrations would be necessary but don't actually do them. | No | false | p4 integrate -n |
| reversemapping | Reverse the mappings in the branch view, with the target files and source files exchanging place. | No | false | p4 integrate -r |
| propagatetype | Propagate the source file's filetype to the target file. | No | false | p4 integrate -t |
| dontcopytoclient | Don't copy newly branched files to the client. | No | false | p4 integrate -v |
| branch | If not null, use this as the integration branch specification. | No | false | p4 integrate -b branch |
| maxfiles | If positive, integrate only the first maxfiles files. | No | 0 |
Branch or merge all files under the "//depot/dev/..." path to the corresponding files under the "//depot/rel2/..." path. If there is no corresponding file under the "//depot/rel2/..." path, this creates it.
<p4jintegrate
fromfile="//depot/dev/..."
tofile="//depot/rel2/..."
/>
Branch or merge all fromfiles contained in the branch view "rel2br" into the corresponding tofiles as mapped through the branch view.
<p4jintegrate
branch="rel2br"
/>
Branch or merge those fromfiles contained in the branch view "rel2br" that map to the tofiles "//depot/rel2/headers/...".
<p4jintegrate
branch="rel2br"
tofile="//depot/rel2/headers/..."
/>
Branch or merge fromfile "//depot/rel2/README" from its tofile as mapped through the branch view "rel2br".
<p4jintegrate
reversemapping="true"
branch="rel2br"
tofile="//depot/rel2/README"
/>
Create or edit a job specification. A job is a defect, enhancement, or other unit of intended work. When a new job is saved a job name of the form jobNNNNNN is created. If a jobName is given that named job will be created, or if the job already exists, it will be modified.
Note: The fields from the "field" nested elements will override the values set on attributes, such as 'status', 'description', etc.
| Attribute | Description | Required | Default | P4 Command |
| delete | If true, the job will be deleted. | No | false | p4 job -d |
| name | The job name of the form jobNNNNNN. 'new' generates a sequenced job number. | No | null | |
| status | The job status. Either 'open', 'closed', or 'suspended'. Can be changed. | No | null | |
| creator | The user who created the job. Can be changed. | No | null | |
| description | Comments about the job. Required for creating a job. | No | null | |
| property | The property to be set with the job ID. | No | null |
Create a new job with description "New Java bug" and status "suspended". Note, the description will be overridden by the nested element "field" name-value pairs. Therefore, the final description will be "Override New Java bug description". The new job ID will be set to the "p4.job" property.
<p4jjob
name="new"
description="New Java bug.">
<field name="Status" value="suspended"/>
<field name="Description" value="Override New Java bug description."/>
</p4jjob>
Change the status of a job to "close".
<p4jjob
name="job123"
status="closed"
/>
Delete a job.
<p4jjob
name="job123"
delete="true"
/>
Reports the list of all jobs currently known to the system. If a file (pattern) is given, only fixes for submitted changelists affecting that file (or set of files) are listed. The file pattern may include wildcards and/or a revision number range. See 'p4 help revisions' for help specifying revisions.
| Attribute | Description | Required | Default | P4 Command |
| maxjobs | If greater than zero, limit the output to the first maxjobs jobs. | No | 0 | p4 jobs -m |
| longdescriptions | If true, return full descriptions, otherwise show only a subset (typically the first 128 characters, but this is not guaranteed). | No | false | p4 jobs -l |
| reverseorder | If true, reverse the normal sort order. | No | false | p4 jobs -r |
| includeintegrated | If true, include any fixes made by changelists integrated into the specified files. | No | false | p4 jobs -i |
| jobview | If not null, this should be a string in format detailed by "p4 help jobview" used to restrict jobs to those satisfying the job view expression. | No | null | p4 jobs -e |
List all jobs attached to changelists that include revisions of the "//depot/proj/file1.java" file.
<p4jjobs
files="//depot/proj/file1.java#1"
/>
List all jobs attached to changelists that include revisions of the "//depot/proj/file1.java" file or revisions of files that were integrated into the "//depot/proj/file1.java" file.
<p4jjobs
includeintegrated="true"
files="//depot/proj/file1.java"
/>
List all jobs that contain the word gui in any field.
<p4jjobs
jobview="gui"
/>
List all jobs that contain the word gui in any field and the word joe in the "Submitted-By:" field.
<p4jjobs
jobview="gui Submitted-By=joe"
/>
List all jobs that have the word fast or quick in any field, and that are linked to changelists that affected files under the "//depot/proj/..." path.
<p4jjobs
jobview="fast|quick"
files="//depot/proj/..."
/>
Create a new label specification or edit an existing label specification. A name is required.
A label is a shorthand for referring to a collection of revisions. See 'p4 help revisions' for information on using labels. A label is either automatic or static.
An automatic label refers to the revisions given in the "View:" and "Revision:" fields.
A static label refers to the revisions associated with the label by the 'tag' or 'labelsync' commands. A static label cannot have a Revision: field.
| Attribute | Description | Required | Default | P4 Command |
| name | The name of label. | Yes | null | |
| description | Description of the label. | No | null | |
| revision | Revision specification for the label. | No | null | |
| locked | Lock the label. | No | false | |
| delete | Delete the label. | No | false | p4 label -d |
| force | Force the update or deletion of a label. | No | false | p4 label -f |
Create a new label "proj1label".
<p4jlabel
name="proj1label"
/>
Create a new label "proj1label" and set it to "locked".
<p4jlabel
name="proj1label"
locked="true"
/>
Synchronize a label with the current client contents. Labelsync causes the named label to reflect the current contents of the client. It records the last revision of each file taken onto the client. The label's name can subsequently be used in a revision specification as @label to refer to the revision of a file as stored in the label.
Without a file argument, labelsync causes the label to reflect the contents of the whole client, by adding, deleting, and updating the label. If a file is given, labelsync updates only that named file.
If the file argument includes a revision specification, then that revision is used instead of the revision taken by the client. If the revision specified is a deleted revision, then the label will include that deleted revision. See 'p4 help revisions' for help specifying revisions.
If the file argument includes a revision range specification, then only files selected by the revision range are updated, and the highest revision in the range is used.
| Attribute | Description | Required | Default | P4 Command |
| name | The name of label. | Yes | null | p4 labelsync -l label |
| noupdate | If true, lists how the label would be affected, but doesn't actually update the label. | No | false | p4 labelsync -n |
| addfiles | If true, it causes labelsync to add the named file to the label; no files will be deleted from the label. | No | false | p4 labelsync -a |
| deletefiles | If true, it deletes the named file from the label, regardless of revision. | No | false | p4 labelsync -d |
Sync the label "proj1label" with the client files under the "//depot/proj1/..." path.
<p4jlabelsync
name="proj1label"
files="//depot/proj1/..."
/>
Sync the label "proj1label" with all of the client files.
<p4jlabelsync
name="proj1label"
/>
Lock opened files against changelist submission.
The open files named are locked in the depot, preventing any user other than the current user on the current client from submitting changes to the files. If a file is already locked then the lock request is rejected. If no file names are given then lock all files currently open in the changelist number given or in the 'default' changelist if no changelist number is given.
| Attribute | Description | Required | Default | P4 Command |
| changelist | If positive, use the changelist given instead of the default changelist. | No | 0 (default) | p4 lock -c |
Lock the file "//depot/projA/fast1.c" in the depot.
<p4jlock
files="//depot/projA/fast1.c"
/>
Lock all files under the "//depot/projA/..." path in the depot.
<p4jlock
files="//depot/projA/..."
/>
Move files from one location to another.
Move takes an already opened file and moves it from one client location to another, reopening it as a pending depot move. When the file is submitted with 'submit', its depot file is moved accordingly.
Wildcards in fromFile and toFile must match. The fromFile must be a file opened for add or edit.
'opened' lists pending moves. 'diff' can compare a moved client file with its depot original, 'sync' can schedule an update of a moved file, and 'resolve' can resolve the update.
A client file may be moved many times before it is submitted. Moving a file back to its original location will undo a pending move, leaving unsubmitted content intact. Using 'revert' will both undo the move and revert the unsubmitted content.
| Attribute | Description | Required | Default | P4 Command |
| fromfile | Source file and revision specifiers separated by space. If the path contains whitespace, it must be double-quoted. | Yes | null | |
| tofile | Target file and revision specifiers separated by space. If the path contains whitespace, it must be double-quoted. | Yes | null | |
| changelist | If specified, the files are opened in the numbered pending changelist instead of the 'default' changelist. | No | -1 (unknown) | p4 move -c changelist |
| listonly | If true, don't actually perform the move, just return what would happen if the move was performed. | No | false | p4 move -n |
| force | If true, force a move to an existing target file; the file must be synced and not opened. Note that the originating source file will no longer be synced to the client. | No | false | p4 move -f |
| noclientmove | If true, bypasses the client file rename. This option can be used to tell the server that the user has already renamed a file on the client. The use of this option can confuse the server if you are wrong about the client's contents. Only works for 2009.2 and later servers; earlier servers will produce a RequestException if you set this true. | No | false | p4 move -k |
| filetype | If non-null, the file is reopened as that filetype. If the filetype given is a partial filetype, that partial filetype is combined with the current filetype. | No | null | p4 move -t filetype |
Assuming that "file1.c" is open for add or edit, move "file1.c" to "file2.c".
<p4jmove
fromfile="file1.c"
tofile="file2.c"
/>
Moving open files from directory "d1" to directory "d2".
<p4jmove
fromfile="//depot/d1/..."
tofile="//depot/d2/..."
/>
Move opened files between changelists or change the files' type. Reopen takes an already opened file and reopens it for the current user, optionally changing its changelist or filetype. The changelist must have previously been created with 'change' or may be the 'default' changelist.
| Attribute | Description | Required | Default | P4 Command |
| tochangelist | If given, the file is moved to that changelist; that changelist must have been previously created. Otherwise the file is opened in the 'default' (unnumbered) changelist. | No | 0 (default) | p4 reopen -c |
| filetype | If non-null, the file is reopened as that filetype. If the filetype given is a partial filetype, that partial filetype is combined with the current filetype. | No | null | p4 reopen -t filetype |
Reopen all open files as text files with keyword expansion.
<p4jreopen
filetype="text+k"
files="//..."
/>
Move all open files under directory //depot/proj1 or that are named README to pending changelist "410".
<p4jreopen tochangelist="410">
<file path="//depot/proj1/..."/>
<file path="//.../README"/>
</p4jreopen>
Move all open ".exe" files to the default changelist, overwriting older revisions of those files in the depot.
<p4jreopen
filetype="binary+S"
files="//....exe"
tochangelist="0"
/>
Merge open files with other revisions or files. Automatically resolve the results of a previous Perforce file integration. Note also that having safeMerge, acceptTheirs, acceptYours, and forceResolve all set to false in the associated ResolveFilesAutoOptions object results in "-am" behavior.
| Attribute | Description | Required | Default | P4 Command |
| safemerge | If true, only do "safe" resolves, as documented for the 'p4 resolve' "-as" option. | No | false | p4 resolve -as |
| accepttheirs | If true, automatically accept "their" changes, as documented for the 'p4 resolve' "-at" option. | No | false | p4 resolve -at |
| acceptyours | If true, automatically accept "your" changes, as documented for the 'p4 resolve' "-ay" option. | No | false | p4 resolve -ay |
| showactionsonly | If true, don't do the actual resolve, just return the actions that would have been performed for the resolve. | No | false | p4 resolve -n |
| forceresolve | Forces auto-mode resolve to accept the merged file even if there are conflicts. Corresponds to the "-af" option. | No | false | p4 resolve -af |
Automatically accept the Perforce-recommended file revision: if theirs is identical to base, accept yours; if yours is identical to base, accept theirs; if yours and theirs are different from base, and there are no conflicts between yours and theirs; accept merge; other wise, there are conflicts between yours and theirs, so skip this file. This example corresponds to the "-am" option.
<p4jresolve
files="//depot/projA/test-branch/src/test/..."
/>
Accept yours, ignore theirs. This example corresponds to the "-ay" option.
<p4jresolve
acceptyours="true"
files="//depot/projA/test-branch/src/test/..."
/>
Discard changes from opened files. Revert an open file back to the revision previously synced from the depot, discarding any pending changelists or integrations that have been made. This command requires naming files explicitly. After running revert the named files will no longer be locked or open.
| Attribute | Description | Required | Default | P4 Command |
| noupdate | If true, it lists what files would be affected but does not actually revert them. | No | false | p4 revert -n |
| changelist | If given, it limits the revert to files opened under the given, pending changelist. | No | 0 (default) | p4 revert -c |
| revertonlyunchanged | If true, it reverts only those files which are opened for edit or integrate and are unchanged or missing. Files with pending integration records are left open. | No | false | p4 revert -a |
| noclientrefresh | If true, bypasses the client file refresh. It can be used to make the server believe the file is no longer open, but keeps the file unchanged in the client workspace. | No | false | p4 revert -k |
Revert every file you have open, in every one of your pending changelists, to its pre-opened state.
<p4jrevert
files="//..."
/>
Revert every file open in the default changelist to its pre-opened state.
<p4jrevert
changelist="default"
files="//..."
/>
Preview a reversion of all open ".txt" files in the current directory, but don't actually perform the revert.
<p4jrevert
noupdate="true"
files="*.txt"
/>
Revert all unchanged files. This command is often used before submitting a changelist.
<p4jrevert
revertonlyunchanged="true"
/>
Store files from a pending changelist in the depot, without submitting them.
The 'shelve' command creates, modifies or deletes shelved files in a pending changelist. Shelved files persist in the depot until they are deleted (using the 'deletefiles' attribute) or replaced by subsequent shelve commands. After shelving, the user can revert the files and restore them later using 'unshelve'. Other users can 'unshelve' the stored files into their own workspaces.
Files that have been shelved can be accessed by the 'diff', 'diff2', 'files' and 'print' commands using the revision specification '@=change', where 'change' is the pending changelist number.
Adds files from the user's specified changelist then shelves those files into the depot.
If a file pattern is specified, 'shelve' limits the list of files to those matching the pattern.
| Attribute | Description | Required | Default | P4 Command |
| changelist | The pending changelist that contains shelved files to be created, deleted, or modified. | Yes | p4 shelve -c | |
| forceshelve | If true, it forces overwriting any existing shelved files in a pending changelist. | No | false | p4 shelve -f |
| replacefiles | If true, enables you to replace all shelved files in that changelist with the files opened in your own workspace at that changelist number. Only the user and client workspace of the pending changelist is allowed to replace its shelved files. | No | false | p4 shelve -r |
| deletefiles | If true, it deletes the shelved files in the specified changelist so that they can no longer be unshelved. By default only the user and client of the pending changelist is allowed to delete its shelved files. | No | false | p4 shelve -d |
Stores the files under the "//depot/proj1/dev/..." path in the changelist "410" to the Perforce server.
<p4jshelve
changelist="410"
files="//depot/proj1/dev/..."
/>
Deletes the shelved files in the specified changelist "410" so that they can no longer be unshelved.
<p4jshelve
changelist="410"
deletefiles="true"
/>
Commits a pending changelist and its files to the depot.
With no argument the 'submit' command attempts to submit all files in the 'default' changelist. Submit provides the user with a dialog similar to 'change' so the user can compose a changelist description. In this dialog the user is presented with the list of files open in changelist 'default'. Files may be deleted from this list but they cannot be added. (Use an open command (edit, add, delete) to add additional files to a changelist.).
If a (single) file pattern is given, only those files in the 'default' changelist that match the pattern will be submitted.
| Attribute | Description | Required | Default | P4 Command |
| changelistdescription | The description of the changelist. | No | null | p4 submit -d |
| changelist | Submits the numbered pending changelist that has been previously created or a failed submit. | No | 0 (default) | p4 submit -c |
| changelistproperty | Name of property to set the new changelist number, if the Perforce server renumbers the change. | No | null | |
| needsresolveproperty | Name of property to be set to true, if the submit requires a resolve. | No | null | |
| reopen | If true, it allows submitted files to remain open (on the client's default changelist) after the submit has completed. | No | false | p4 submit -r |
| job | List of job IDs, separated by whitespace, for jobs that will have their status changed to fixed or "jobStatus". | No | null | |
| jobstatus | Status of jobs will be set on a successful submit; if null the jobs will be marked fixed. | No | null | p4 submit -s |
Commits a pending changelist and its files to the depot.
<p4jsubmit
changelistdescription="Updated Java classes."
/>
Submits the numbered pending changelist "410" that has been previously created or a failed submit.
<p4jsubmit
changelist="410"
/>
Submits files under the "//depot/proj1/newfiles/..." path in the numbered pending changelist "410" to the depot.
<p4jsubmit
changelist="410"
files="//depot/proj1/newfiles/..."
/>
Synchronize the client with its view of the depot.
Sync updates the client workspace to reflect its current view (if it has changed) and the current contents of the depot (if it has changed). The client view is used to map client file names to depot file names and vice versa.
Sync adds files that are in the client view but which have not been retrieved before. Sync deletes previously retrieved files which are no longer in the client view or have been deleted from the depot. Sync updates files which are still in the client view and which have been updated in the depot.
Normally, sync affects all files in the client workspace. If file arguments are given, sync limits its operation to those files. The file arguments may contain wildcards.
If the file argument includes a revision specifier, then the given revision is retrieved. Normally, the head revision is retrieved. See 'p4 help revisions' for help specifying revisions.
If the file argument includes a revision range specification, then only files selected by the revision range are updated, and the highest revision in the range is used.
Normally, sync will not clobber files in the client workspace that the user has made writable. Setting the 'clobber' option in the client spec disables this safety check.
| Attribute | Description | Required | Default | P4 Command |
| forceupdate | If true, it forces re-sync even if the client already has the file, and clobbers writable files. This flag doesn't affect open files. | No | false | p4 sync -f |
| noupdate | If true, it causes sync not to update the client workspace, but to list what normally would be updated. | No | false | p4 sync -n |
| clientbypass | If true, it bypasses the client file update. It can be used to make the server believe that a client workspace already has the file. Typically this flag is used to correct the Perforce server when it is wrong about what files are on the client. Use of this option can confuse the server if you are wrong about the client's contents. | No | false | p4 sync -k |
| serverbypass | If true, it populates the client workspace, but does not update the server to reflect those updates. Any file that is already sync'ed or opened will be bypassed with a warning message. This option is very useful for build clients or when publishing content without the requirement of saving the client workspace state. | No | false | p4 sync -p |
Copy the latest revision of all files from the depot to the client workspace, as mapped through the client view. If the file is already open in the client workspace, or if the latest revision of the file exists in the client workspace, it is not copied.
<p4jsync/>
Copy the fourth revision of "file.c" to the client workspace, with the same exceptions as in the example above.
<p4jsync
files="file.c#4"
/>
Copy all the files under the "//depot/proj1" path from the depot to the client workspace, as mapped through the client view. Don't copy the latest revision; use the revision of the file in the depot after changelist "21" was submitted.
<p4jsync
files="//depot/proj1/...@21"
/>
Force update of all the files under the "//depot/proj1" path from the depot to the client workspace, even if the client already has the file, and clobbers writable files. This option doesn't affect open files.
<p4jsync
forceupdate="true"
files="//depot/proj1/..."
/>
Bring the workspace into sync with a label, but preserve unlabeled files in the workspace.
<p4jsync
files="@mylabelname"
/>
Tag files with a label.
Tag associates the named label with the file revisions indicated by the file argument. Once file revisions are tagged with a label, revision specifications of the form '@label' can be used to refer to them.
If the file argument does not include a revision specification, the head revisions will be tagged. See 'p4 help revisions' for revision specification options.
If the file argument includes a revision range specification, only the files with revisions in that range will be tagged. Files with more than one revision in the range will be tagged at the highest revision.
The "delete" (-d flag) option deletes the association between the specified files and the label, regardless of revision.
| Attribute | Description | Required | Default | P4 Command |
| label | Name of the label to be associated with the files. | Yes | p4 tag -l | |
| listonly | If true, it lists the files that would be tagged, but doesn't actually do anything. | No | false | p4 tag -n |
| delete | If true, it deletes the association between the specified files and the label, regardless of revision. | No | false | p4 tag -d |
Tag the head revisions of files under the "//depot/1.0/..." path with label "rel1". If the label "rel1" does not exist, create it.
<p4jtag
label="rel1"
files="//depot/1.0/..."
/>
Tag the most recent revisions as of the submission of changelist "1234" of files under the "//depot/1.0/..." path with label build. If the label build does not exist, create it.
<p4jtag
files="//depot/1.0/...@1234"
label="build"
/>
Release locked files but leave them open.
The unlock command releases a lock on an open file in a pending changelist. If the file is open in a specific pending changelist other than 'default', then the -c flag is required to specify the pending changelist. If no file name is given then all files in the designated changelist are unlocked.
| Attribute | Description | Required | Default | P4 Command |
| changelist | If positive, use the changelist given instead of the default changelist. | No | 0 (default) | p4 unlock -c |
| forceunlock | Force unlock of any file; normally files can only be unlocked by their owner. The forceunlock (-f flag) option requires 'admin' access granted by 'p4 protect'. | No | false | p4 unlock -f |
Unlock the file "//depot/projA/fast1.c" in the depot.
<p4junlock
files="//depot/projA/fast1.c"
/>
Force unlock all files under "//depot/projA/..." in the depot.
<p4junlock
files="//depot/projA/..."
forceunlock="true"
/>
Restore shelved files from a pending change into a workspace.
The unshelve command retrieves the shelved files from a pending changelist and copies them into a pending changelist on the invoking user's workspace. Unshelving files from a pending changelist is restricted by the user's permissions on the files. A successful unshelve operation places the shelved files on the user's workspace with the same open action and pending integration history as if it had originated from that user and client.
| Attribute | Description | Required | Default | P4 Command |
| fromchangelist | The source pending changelist that contains the shelved files. | Yes | 0 (default) | p4 unshelve -s |
| tochangelist | The target changelist to receive the shelved files. | No | 0 (default) | p4 unshelve -c |
| forceunshelve | If true, it forces the clobbering of any writeable but unopened files that are being unshelved. | No | false | p4 unshelve -f |
| preview | If true, previews what would be unshelved without actually changing any files or metadata. | No | false | p4 unshelve -n |
Restores the shelved files from changelist 410 to the default changelist.
<p4junshelve
fromchangelist="410"
/>
Restores the shelved files from changelist 410 to the changelist 810.
<p4junshelve
fromchangelist="410"
tochangelist="810"
/>
Force unshelve of the shelved files in the specified changelist 410.
<p4junshelve
forceunshelve="true"
fromchangelist="410"
tochangelist="410"
/>
| Sept 2010 | V1.0 | Initial Release |