Files: P4 Code Review files
Get file data
Summary
Get file data for the specified file
GET /api/v11/files/{id}
Description
Get file data for the specified file.
Parameters
| Parameter | Description | Type | Parameter Type | Required |
|---|---|---|---|---|
|
id |
File ID, this is the full filepath including the filename encoded to URL safe Base64. Various tools are available online to encode the id to URL safe Base64, for example: BASE64 Decode and Encode. |
string |
path |
Yes |
| fileRevision |
Specify the revision of the file using one of the following options:
Where nnn is the revision or changelist number you want. |
string |
query |
No |
Example usage
Get file data for a specific revision of a file
Get file data for //depot/main/myfile.txt revision 3. The full filepath and filename must be encoded in URL safe Base64.
curl -u "username:ticket" "https://myswarm-url/api/v11/files/Ly9kZXBvdC9tYWluL215ZmlsZS50eHQ?fileRevision=#3"
P4 Code Review responds with:
HTTP/1.1 200 OK
{
"error": null,
"messages": [],
"data" : {
"filename":"//depot/main/myfile.txt"
"contentLink": "http://myswarm-url/view/depot/main/myfile.txt",
"fileRevision": "#3",
"contentType": "text/plain",
"changeId": "12871"
}
}
If a request fails
<error code>:
- 400 Invalid file revision specified. Must be one of the following: @ or @= followed by the changelist number, or # followed by the file revision number.
- 403 Insufficient permissions to access the file
- 404 File does not exist
HTTP/1.1 <response error code>
{
"error": <error code>,
"messages": [{
"code" : "<code string>",
"text" : "<error message>"
}],
"data" : null
}
Get a file diff
Summary
Get a file diff for the specified file
GET /api/v11/files/{id} /diff
Description
Get a file diff for the specified file
Parameters
| Parameter | Description | Type | Parameter Type | Required |
|---|---|---|---|---|
|
id |
File ID, this is the full filepath including the filename for the diff encoded to URL safe Base64. Various tools are available online to encode the id to URL safe Base64, for example: BASE64 Decode and Encode. |
string |
path |
Yes |
|
from |
Specify the file revision to compare against in the form %23{revision-number}. This is the revision that would be displayed on the left side of a P4 Code Review diff. If the from parameter is not specified, the head The most recent revision of a file within the depot. Because file revisions are numbered sequentially, this revision is the highest-numbered revision of that file. revision is used. |
string |
query |
No |
|
to |
Specify the file revision being compared in the form %23{revision-number}. This is the revision that would be displayed on the right side of a P4 Code Review diff. |
string |
query |
Yes |
|
type |
Specify the file type for the diff:
|
string |
query |
No |
|
lines |
Specify the number of lines of context around each diff returned in the response. |
integer |
query |
No |
|
ignoreWs |
Specify the whitespace options for the diff:
|
integer |
query |
No |
|
max_size |
P4 Code Review limits the size of files displayed in both reviews and standard file views. Files larger than 100 KB are paginated. How the files are paginated depends on the type of review being displayed.
Specify the maximum sized file that can be returned as a diff for an edit:
The lowest max_size value defaults to 50 bytes. If you set the max_size value lower than 50 bytes then P4 Code Review will ignore it. For information on known limitations with pagination, see max_size in Files configuration. When a file is in the edit state, depending on the max_size value, a fetchContent flag is set in the response. The fetchContent flag determines if the size of a file is larger than the max_size value and accordingly enables or disables the show more context buttons in the file diff panel. For more information about the show more context buttons, see File diff panel. Files larger than the max_size value sets the fetchContent flag to false. When the fetchContent flag is set to false, all the show more context buttons in the file diff panel are disabled. When the fetchContent flag is set to true, all the show more context buttons in the file diff panel are enabled. |
integer |
query |
No |
|
max_diffs |
Specify the maximum number of diff sections (chunks) to return in the response:
|
integer |
query |
No |
|
offset |
Specify the diff section (chunk) to start displaying from. The number of diff sections displayed from the offset parameter value is governed by the max_diffs parameter value specified. For example, if you just want to return the third diff section, set offset=2 and max_diffs=1. |
integer |
query |
No |
|
fromFile |
If the file has been moved or renamed, and edited, use the fromFile parameter to specify the original filepath including the filename encoded to URL safe Base64. Various tools are available online to encode the fromFile to URL safe Base64, for example: BASE64 Decode and Encode. |
string |
query |
No |
Example usage
Get a file diff
Get the file diff between revisions 233 and 234 of //projects/acme/main/src/aliqitaq/quosquo/do/53.txt and don't return whitespace characters. The full filepath and filename must be encoded in URL safe Base64.
curl -u "username:ticket" "https://myswarm-url/api/v11/files/Ly9wcm9qZWN0cy9hY21lL21haW4vc3JjL2FsaXFpdGFxL3F1b3NxdW8vZG8vNTMudHh0/diff?from=%233&to=%234&ignoreWs=0&type=file"
P4 Code Review responds with:
HTTP/1.1 200 OK
{
"error": null,
"messages": [],
"data" : {
"isCut": false,
"isSame": false,
"header": "--- a///projects/acme/main/src/aliqitaq/quosquo/do/53.txt#3\n+++ b///projects/acme/main/src/aliqitaq/quosquo/do/53.txt#4\n",
"summary": {
"adds": 1,
"deletes": 0,
"updates": 0
},
"diffs": [
"@@ -30,10 +30,12 @@\n このリリースは、バージョン1.0.1g の OpenSSL ライブラリをリンクすること\n によって、Heartbleed CVE-2014-0160 脆弱性に対処しています。\n \n --------------------------------------------------------------------------\n \n+Hello\n+\n 以前のリリースとの互換性\n -------------------------\n \n 1. PERFORCE ブローカは、2007.2以降にリリースされたPERFORCE クライアント及び\n サーバと互換性があります。 \n"
],
"paging": {
"diffs": 1,
"offset": null
}
}
}
Get a file diff when the file size is greater than max_size value
Get the file diff between revisions 232 and 40 of //jam/main/src/compile3.c and don't return whitespace characters. The full filepath and filename must be encoded in URL safe Base64. In the response code, the fetchContent flag is set to false as the file size is greater than the max_size value.
curl -u "username:ticket" "https://myswarm-url/api/v11/files/Ly9qYW0vbWFpbi9zcmMvY29tcGlsZTMuYw/diff?from=%232&to=%40%3D13444&ignoreWs=0&type=file"
P4 Code Review responds with:
HTTP/1.1 200 OK
{
"error": null,
"messages": [],
"data": {
"isCut": 1000,
"isSame": false,
"header": "--- a///jam/main/src/compile3.c#2\n+++ b///jam/main/src/compile3.c@=13444\n",
"summary": {
"adds": 1,
"deletes": 3,
"updates": 3
},
"fetchContent": false,
"diffs": [
"@@ -23357,11 +23357,10 @@\n *\tcompile_set() - compile the \"set variable\" statement\n *\tcompile_setcomp() - support for `rule` - save parse tree \n *\tcompile_setexec() - support for `actions` - save execution string \n *\tcompile_settings() - compile the \"on =\" (set variable on exec) statement\n *\tcompile_switch() - compile 'switch' rule\n- * * External routines:\n *\n *\tcompile_foreach() - compile the \"for x in y\" statement\n *\tcompile_if() - compile 'if' rule\n *\tcompile_include() - support for 'include' - call include() on file\n *\tcompile_local() - declare (and set) local variables\n",
"@@ -24981,24 +24980,10 @@\n *\tcompile_set() - compile the \"set variable\" statement\n *\tcompile_setcomp() - support for `rule` - save parse tree \n *\tcompile_setexec() - support for `actions` - save execution string \n *\tcompile_settings() - compile the \"on =\" (set variable on exec) statement\n *\tcompile_switch() - compile 'switch' rule\n- * * External routines:\n- *\n- *\tcompile_foreach() - compile the \"for x "
],
"paging": {
"diffs": 2,
"offset": null
}
}
}
Get a file diff when the file size is not greater than max_size value
Get the file diff between revisions 232 and 40 of //jam/main/src/compile3.c and don't return whitespace characters. The full filepath and filename must be encoded in URL safe Base64. In the response code, the fetchContent flag is set to true as the file size is not greater than the max_size value.
curl -u "username:ticket" "https://myswarm-url/api/v11/files/Ly9qYW0vbWFpbi9zcmMvY29tcGlsZTMuYw/diff?from=%232&to=%40%3D13444&ignoreWs=0&type=file"
P4 Code Review responds with:
HTTP/1.1 200 OK
{
"error": null,
"messages": [],
"data": {
"isCut": false,
"isSame": false,
"header": "--- a///jam/main/src/compile3.c#2\n+++ b///jam/main/src/compile3.c@=13444\n",
"summary": {
"adds": 1,
"deletes": 3,
"updates": 3
},
"fetchContent": true,
"diffs": [
"@@ -23357,11 +23357,10 @@\n *\tcompile_set() - compile the \"set variable\" statement\n *\tcompile_setcomp() - support for `rule` - save parse tree \n *\tcompile_setexec() - support for `actions` - save execution string \n *\tcompile_settings() - compile the \"on =\" (set variable on exec) statement\n *\tcompile_switch() - compile 'switch' rule\n- * * External routines:\n *\n *\tcompile_foreach() - compile the \"for x in y\" statement\n *\tcompile_if() - compile 'if' rule\n *\tcompile_include() - support for 'include' - call include() on file\n *\tcompile_local() - declare (and set) local variables\n",
"@@ -24981,24 +24980,10 @@\n *\tcompile_set() - compile the \"set variable\" statement\n *\tcompile_setcomp() - support for `rule` - save parse tree \n *\tcompile_setexec() - support for `actions` - save execution string \n *\tcompile_settings() - compile the \"on =\" (set variable on exec) statement\n *\tcompile_switch() - compile 'switch' rule\n- * * External routines:\n- *\n- *\tcompile_foreach() - compile the \"for x in y\" statement\n- *\tcompile_if() - compile 'if' rule\n- *\tcompile_include() - support for 'include' - call include() on file\n- *\tcompile_local() - declare (and set) local variables\n- *\tcompile_null() - do nothing -- a stub for parsing\n- *\tcompile_rule() - compile a single user defined rule\n- *\tcompile_rules() - compile a chain of rules\n- *\tcompile_set() - compile the \"set variable\" statement\n- *\tcompile_setcomp() - support for `rule` - save parse tree \n- *\tcompile_setexec() - support for `actions` - save execution string \n- *\tcompile_settings() - compile the \"on =\" (set variable on exec) statement\n- *\tcompile_switch() - compile 'switch' rule\n */\n /*\n * Copyright 1993, 1995 Christopher Seiwald.\n * * External routines:\n *\n",
"@@ -36086,10 +36071,18 @@\n *\tcompile_set() - compile the \"set variable\" statement\n *\tcompile_setcomp() - support for `rule` - save parse tree \n *\tcompile_setexec() - support for `actions` - save execution string \n *\tcompile_settings() - compile the \"on =\" (set variable on exec) statement\n *\tcompile_switch() - compile 'switch' rule\n+ **\n+ ** Adding new block\n+ ** Adding new block\n+ ** Adding new block\n+ ** Adding new block\n+ ** Adding new block\n+ ** Adding new block\n+ ** Adding new block\n * * External routines:\n *\n *\tcompile_foreach() - compile the \"for x in y\" statement\n *\tcompile_if() - compile 'if' rule\n *\tcompile_include() - support for 'include' - call include() on file\n",
"@@ -57336,23 +57329,10 @@\n *\tcompile_setexec() - support for `actions` - save execution string \n *\tcompile_settings() - compile the \"on =\" (set variable on exec) statement\n *\tcompile_switch() - compile 'switch' rule\n * * External routines:\n *\n- *\tcompile_foreach() - compile the \"for x in y\" statement\n- *\tcompile_if() - compile 'if' rule\n- *\tcompile_include() - support for 'include' - call include() on file\n- *\tcompile_local() - declare (and set) local variables\n- *\tcompile_null() - do nothing -- a stub for parsing\n- *\tcompile_rule() - compile a single user defined rule\n- *\tcompile_rules() - compile a chain of rules\n- *\tcompile_set() - compile the \"set variable\" statement\n- *\tcompile_setcomp() - support for `rule` - save parse tree \n- *\tcompile_setexec() - support for `actions` - save execution string \n- *\tcompile_settings() - compile the \"on =\" (set variable on exec) statement\n- *\tcompile_switch() - compile 'switch' rule\n- * * External routines:\n *\n *\tcompile_foreach() - compile the \"for x in y\" statement\n *\tcompile_if() - compile 'if' rule\n *\tcompile_include() - support for 'include' - call include() on file\n *\tcompile_local() - declare (and set) local variables\n",
"@@ -99842,11 +99822,11 @@\n *\tcompile_setcomp() - support for `rule` - save parse tree \n *\tcompile_setexec() - support for `actions` - save execution string \n *\tcompile_settings() - compile the \"on =\" (set variable on exec) statement\n *\tcompile_switch() - compile 'switch' rule\n * * External routines:\n- *\n+ *****\n *\tcompile_foreach() - compile the \"for x in y\" statement\n *\tcompile_if() - compile 'if' rule\n *\tcompile_include() - support for 'include' - call include() on file\n *\tcompile_local() - declare (and set) local variables\n *\tcompile_null() - do nothing -- a stub for parsing\n",
"@@ -99870,11 +99850,34 @@\n *\tcompile_setcomp() - support for `rule` - save parse tree \n *\tcompile_setexec() - support for `actions` - save execution string \n *\tcompile_settings() - compile the \"on =\" (set variable on exec) statement\n *\tcompile_switch() - compile 'switch' rule\n * * External routines:\n- *\n+ * **\n+ ***\n+ ***\n+ ***\n+ * **\n+ ***\n+ ***\n+ ***\n+ * **\n+ ***\n+ ***\n+ ***\n+ * **\n+ ***\n+ ***\n+ ***\n+ * **\n+ ***\n+ ***\n+ ***\n+ * **\n+ ***\n+ ***\n+ ***\n *\tcompile_foreach() - compile the \"for x in y\" statement\n *\tcompile_if() - compile 'if' rule\n *\tcompile_include() - support for 'include' - call include() on file\n *\tcompile_local() - declare (and set) local variables\n *\tcompile_null() - do nothing -- a stub for parsing\n",
"@@ -99968,11 +99971,11 @@\n *\tcompile_setcomp() - support for `rule` - save parse tree \n *\tcompile_setexec() - support for `actions` - save execution string \n *\tcompile_settings() - compile the \"on =\" (set variable on exec) statement\n *\tcompile_switch() - compile 'switch' rule\n * * External routines:\n- *\n+ *****\n *\tcompile_foreach() - compile the \"for x in y\" statement\n *\tcompile_if() - compile 'if' rule\n *\tcompile_include() - support for 'include' - call include() on file\n *\tcompile_local() - declare (and set) local variables\n *\tcompile_null() - do nothing -- a stub for parsing\n"
],
"paging": {
"diffs": 7,
"offset": null
}
}
}
Get a file diffs where each individual file diff size is more than 100kb
This endpoint retrieves a paginated portion of a file diff when the total diff exceeds 100kb (this limit is a hard coded pagination limit).
When a file diff exceeds this size, the endpoint response includes a section (or "chunk") of the diff along with metadata and pagination information to request subsequent chunks.
curl --location --request GET 'http://my-swarmurl/api/v11/files/Ly9qYW0vbWFpbi9zcmMvZmlsZW50LmM/diff?from=%231&to=%40%3D12343&ignoreWs=0&type=file' \
--header 'Authorization: Basic YnJ1bm86UGFzc3cwcmQ=
If the file has been added or deleted, the response looks like this:
P4 Code Review responds with:
HTTP/1.1 200 OK
{
"error": null,
"messages": [],
"data": {
"isCut": false,
"isSame": false,
"isContentChunk": 1000,
"contentChunkStart": 0,
"contentChunkEnd": 1000,
"contentChunkStartLine": 1,
"contentChunkEndLine": 33,
"wholeDiffSize": 27582,
"currentDiffChunkSize": 1000,
"header": "--- a/dev/null\n+++ b///depot/Jam/MAIN/src/compile_big.c@=13126\n",
"summary": {
"adds": 33,
"deletes": 0,
"updates": 0
},
"diffs": [
"@@ -1,0 +1,33 @@\n+/*\n+ * Copyright 1993, 1995 Christopher Seiwald.\n+ *\n+ * This file is part of Jam - see jam.c for Copyright information.\n+ */\n+\n+# include \"jam.h\"\n+\n+# include \"lists.h\"\n+# include \"parse.h\"\n+# include \"compile.h\"\n+# include \"variable.h\"\n+# include \"rules.h\"\n+# include \"newstr.h\"\n+# include \"make.h\"\n+# include \"search.h\"\n+\n+/*\n+ * compile.c - compile parsed jam statements\n+ *\n+ * External routines:\n+ *\n+ *\tcompile_foreach() - compile the \"for x in y\" statement\n+ *\tcompile_if() - compile 'if' rule\n+ *\tcompile_include() - support for 'include' - call include() on file\n+ *\tcompile_local() - declare (and set) local variables\n+ *\tcompile_null() - do nothing -- a stub for parsing\n+ *\tcompile_rule() - compile a single user defined rule\n+ *\tcompile_rules() - compile a chain of rules\n+ *\tcompile_set() - compile the \"set variable\" statement\n+ *\tcompile_setcomp() - support for `rule` - save parse tree \n+ *\tcompile_setexec() - support for `actions` - save execution string \n+ *\tcompile_settings() - compile the \"on =\" (set variabl"
],
"paging": {
"diffs": 1,
"offset": null
}
}
}
If the file has been edited, the response looks like this:
{
"error": null,
"messages": [],
"data": {
"isCut": false,
"isSame": false,
"configDiffChunkRow": 51,
"originalLinesData": {
"1": {
"originalLines": [
"@@ -31,10 +31,118 @@\n",
" \tstruct item *next;\n",
" \tint keyval;\t\t\t/* for quick comparisons */\n",
" } ;\n",
" \n",
" /* This structure overlays the one handed to hashenter(). */\n",
"... (truncated) ..."
],
"contentChunkLeftStart": "-31",
"contentChunkLeftStartLine": 31,
"contentChunkLeftEndLine": 40,
"contentChunkLeftEnd": 40,
"contentChunkLeftTotalLines": 10,
"largerChunk": "right",
"contentChunkRightStart": "+31",
"contentChunkRightStartLine": 31,
"contentChunkRightEndLine": 148,
"contentChunkRightEnd": 148,
"contentChunkRightTotalLines": 118,
"currentDiffChunkRows": 51
},
"2": {
"originalLines": [
"@@ -76,11 +184,117 @@\n",
" \t\t\tint nel;\t/* total ITEMs held by this list */\n",
" \t\t\tchar *base;\t/* base of ITEMs array */\n",
" \t\t} lists[ MAX_LISTS ];\n",
" \t} items;\n",
" \n",
"... (truncated) ..."
],
"contentChunkLeftStart": "-76",
"contentChunkLeftStartLine": 76,
"contentChunkLeftEndLine": 86,
"contentChunkLeftEnd": 86,
"contentChunkLeftTotalLines": 11,
"largerChunk": "right",
"contentChunkRightStart": "+184",
"contentChunkRightStartLine": 184,
"contentChunkRightEndLine": 300,
"contentChunkRightEnd": 300,
"contentChunkRightTotalLines": 117,
"currentDiffChunkRows": 51
}
},
"header": "--- a///jam/main/src/hash.c#2\n+++ b///jam/main/src/hash.c@=12373\n",
"summary": {
"adds": 1,
"deletes": 0,
"updates": 2
},
"fetchContent": true,
"diffs": [
"@@ -17,11 +17,11 @@\n * hashdone() - free a hash table, given its handle\n *\n * Internal routines:\n *\n * hashrehash() - resize and rebuild hp->tab, the hash table\n- *\n+ *Internal routines:\n * 4/29/93 - ensure ITEM's are aligned\n */\n \n char \t*hashsccssid=\"@(#)hash.c\t1.14 () 6/20/88\";\n ... (truncated) ...",
"@@ -31,10 +31,51 @@\n \tstruct item *next;\n \tint keyval;\t\t\t/* for quick comparisons */\n } ;\n \n /* This structure overlays the one handed to hashenter(). */\n+/*\n+There are many variations of passages of Lorem Ipsum available, but the majority have suffered alteration in some form, by injected humour, o... (truncated) ...",
"@@ -76,11 +184,51 @@\n \t\t\tint nel;\t/* total ITEMs held by this list */\n \t\t\tchar *base;\t/* base of ITEMs array */\n \t\t} lists[ MAX_LISTS ];\n \t} items;\n \n-\tchar *name;\t/* just for hashstats() */\n+\tchar *name;\t/* just for hashstats() \n+\tThere are many variations of passages of Lorem Ipsum available, but ... (truncated) ..."
],
"paging": {
"diffs": 3,
"offset": null
}
}
}
If a request fails
<error code>:
- 400 Invalid file revision specified.
- 404 File does not exist or you do not have permission to view it
HTTP/1.1 <response error code>
{
"error": <error code>,
"messages": [{
"code" : "<code string>",
"text" : "<error message>"
}],
"data" : null
}
File edit
This API endpoint only supports text files. File edit is a Technology Preview feature.
Features offered in Technology Preview are experimental and not guaranteed to always work as expected. If you have feedback and functionality suggestions, email techpreview@perforce.com.
Summary
Edit the file content and submit or shelve the file
PUT /api/v11/files/{id}
Description
Edit the file content and submit or shelve the file.
Requirements:
- You must have permissions to edit the file.
- If the file version changes while you are editing it or if you are not editing the Head The most recent revision of a file within the depot. Because file revisions are numbered sequentially, this revision is the highest-numbered revision of that file. revision of the file, committing your file changes will overwrite the current head revision of the file.
- File edit is enabled by default but can be disabled by your P4 Code Review administrator, see allow_edits.
If you are unsure, shelving your change is a safer option because it will not overwrite the head revision of the file and you can do a manual resolve when you commit the shelf.
Parameters
| Parameter | Description | Type | Parameter Type | Required |
|---|---|---|---|---|
|
id |
File ID, this is the full filepath including the filename encoded to URL safe Base64. Various tools are available online to encode the id to URL safe Base64, for example: BASE64 Decode and Encode |
string |
path |
Yes |
| content | Specify the entire file content to be shelved or submitted. Lines in the content must be separated with backslash and n characters \n. | string | body | Yes |
| description |
Specify a changelist description. Optional: you can create a review for your change or add it to an existing review by including a review keyword in the Change description. For instruction on creating a review and adding a changelist to a review using review keywords, see Create a review and Add a changelist to a review. |
string | body | No |
| action | Specify the file action as either shelve or submit. | string | body | Yes |
Example usage
Shelve file with edited content
Shelve //depot/main/myfile.txt file with edited content. The full filepath and filename must be encoded in URL safe Base64.
curl -X PUT -H "Content-Type: application/json" -u "username:ticket" -d "@mybodyfilename.txt" "https://myswarm-url/api/v11/files/Ly9kZXBvdC9tYWluL215ZmlsZS50eHQ"
The "mybodyfilename.txt" file contains the file content, description and the shelve action:
{
"content": "My original line\nMy nice new line\nAnother original line"
"description": "Added a new line."
"action": "shelve"
}
P4 Code Review responds with:
HTTP/1.1 200 OK
{
"error": null,
"messages": [],
"data" : {
"filename":"//depot/main/myfile.txt"
"contentLink": "http://myswarm-url/view/depot/main/myfile.txt",
"fileRevision": "@=12896",
"contentType": "text/plain",
"changeId": "12896"
}
}
If a request fails
<error code>:
- 400 Invalid file revision specified. Must be one of the following: @ or @= followed by the changelist number, or # followed by the file revision number.
- 403 Insufficient permissions to submit or shelve the file
- 404 File does not exist
- 500 Submit command failed because a newer revision of the file exists, you must resolve and submit your changes or revert your changes.
HTTP/1.1 <response error code>
{
"error": <error code>,
"messages": [{
"code" : "<code string>",
"text" : "<error message>"
}],
"data" : null
}