p4 obliterate

Permanently removes files and their history (metadata) from the depot.

Syntax

p4 [g-opts] obliterate [-y -A -b -a -h -l -T] [-r alg] [-p | --purged-only] [-q] FileSpec[revSpec]

Syntax conventions

Description

p4 obliterate can be used by Helix Core Server administrators to permanently remove files from the depot.

p4 obliterate requires at least one file pattern as an argument. To perform the obliteration, the -y option is required. Without -y, the p4 obliterate command reports what it would do if -y were included.

If you specify a single revision (for instance, p4 obliterate file#3), only that revision of the file is obliterated. If you specify a revision range (for instance, p4 obliterate file#3,5), only the revisions #3, #4, and #5 are obliterated. See Using revision ranges.

Tip

Because obliterate is permanent, we recommend first using the report mode (without -y).

Warning

The p4 obliterate -y command deletes the server’s copy of a file’s data, precluding any possibility of recovery. The file is removed from the Perforce service, along with all associated metadata, including references to the file in labels and the have list An internal list indicates which files and revisions the client workspace has sync'd from the depot. See 'p4 have' in Helix Core Command-Line (P4) Reference..

After p4 obliterate completes, the service has no record that those files ever existed.

The exception is that the following remain:

any lazy copies made when p4 integrate created a branch if those lazy copies are still in use.
the files in the archive that correspond to those lazy files
any copies of obliterated files in user workspaces, but Helix Core Server does not recognize them

delete as an alternative

Consider whether using the p4 delete command instead of p4 obliterate is appropriate for your needs because p4 delete marks the latest revision as deleted, but leaves earlier revisions in the depot.

purging file content as an alternative

Consider using the -p option to purge file conten while preserving all file metadata.

For example, to permanently remove file content that was submitted in the years 2015 through 2018:
p4 obliterate -p -y file@2015/01/01,2019/01/01

and for a directory:

p4 obliterate -p -y //depot/some/path/...@2015/01/01,2019/01/01

performance consideration

We recommend running this command during a maintenance or quiet period on the server because performance can be affected if a large number of file revisions are being obliterated,

shelve behavior

p4 obliterate myfile does not obliterate a shelf of the file (archive or metadata). When you attempt to unshelve a file that has been obliterated, you will get an error. To recover the content of that file, print the file. To get rid of the shelve, delete the shelf.

p4 obliterate with a file spec does not obliterate a shelf of the file.

Helix Swarm and obliterated files

If a file is obliterated from Helix Core Server and that file is part of a Swarm review, the Swarm review shows Cannot fetch file '//depot/path/to/file.c#1'. File does not exist. If you want Helix Swarm to remove references to, and metadata about, obliterated files, see Obliterate a review in the Helix Swarm Guide.

stream spec obliteration

The administrator can obliterate a stream spec, which is distinct from the files in the stream. See the --obliterate option of p4 stream.

Options

`-y`	Perform the obliterate operation. Tip Because obliterate is permanent, we recommend first using the report mode (without `-y`).
`-A`	Obliterate a revision marked for archive. The overrides the default behavior, which skips archived revisions. Note To remove the metadata and content in the archive depot, use the p4 archive `-p` command. Using `-A` means you can no longer restore the archive nor use `archive -p`
`-b`	Restrict files in the argument range to those that are branched, and to files that are both the first revision and the head revision. This option is useful for removing old branches (where only one revision exists) while preserving files that have been modified post-branch. You can improve the performance of `obliterate -b` by using the `-a` option with `-b`.
`-a`	Skip the archive search and removal phase. File content is not removed. This option is safe to use with the -b option.
`-h`	Skip the search of the have list The list of file revisions currently in the client workspace. (`db.have`) when searching for matching metadata to delete, which tends to save time. This means that `db.have` records are not deleted. With this option, the next time a client workspace that refers to these files is synced, any such files in the workspace will also be removed. This is often the desired behavior in client workspaces on build machines. Do not use this flag when obliterating branches or namespaces for reuse, because the old content on a client will not match the newly-added repository files 2024.2 and later: Note 33 of the journal file notifies edge servers to not delete `db.have` records, which can save time. To learn more, see xref SAG on Journal Notes.
`-l`	Skip the search of labels A special filespec that gives a meaningful name to a set of file revisions. A reference such as @Release2.3-August-2023 might be easier to remember than //depot/project/...@48296 to delete, which might save time if the number of labels is large. Labels are ignored because the `db.label` table is not searched for all possible matching records to delete. This is similar to the `-h` option that skips searching for have list The list of file revisions currently in the client workspace. metadata to delete.
`-T`	Required for reporting and obliterating task stream paths.
`-r alg`	Use if you want to select the algorithm for purging the integration records. The original algorithm scans the integration table looking for a match with the rev table. The new algorithm scans the rev table looking for a match with the integration table. Searches using a changelist number only operate on the rev table. Therefore, it is more efficient to use the new algorithm for file arguments that includes a changelist number or revision. By default, the Helix Core Server automatically determines which algorithm is likely to be most efficient. To force the original algorithm, set `alg` to `0`, and to force the new algorithm, set `alg` to `1`.
-p	Mark the revison as purged and leave the integration history intact, rather than removing the records.
`--purged-only`	Only remove previously purged records created by an earlier call to `p4 obliterate -p -y` Ignores the `-b` and `-h` options and enables the `-a` option. Removes all the associated meta-data (integration, client, and work records).
`-q`	Supresses the output messages concerning purged or deleted revision records or deleted archives.
`g-opts`	See Global options.

Usage notes

Can File Arguments Use Revision Specifier?	Can File Arguments Use Revision Range?	Minimal Access Level Required
Yes	Yes	`admin`

p4 obliterate is one way to reclaim disk space from files that are no longer required, or to clean up mistakes made by users who create file hierarchies in the wrong place. Do not use operating system commands (erase, rm, and their equivalents) to remove files from the Helix Core Server root by hand.
A better way to save disk space is to relocate infrequently-accessed files onto lower-performance (or detachable) storage. Instead of obliterating files outright, consider using p4 archive and p4 restore in conjunction with an archive depot. To learn more, see archive depots. With archive depots, file history is preserved and available to all users, and file contents can be moved to offline or near-line storage.
Obliterating files can alter the behavior of user commands. Syncing to an obliterated file does not remove the file from your client workspace because the file is no longer associated with any client workspace. Syncing to an obliterated revision of a file will either report that the file does not exist (if all revisions were obliterated), or provide you with the most recent non-obliterated revision of the file.
Obliterating files in revision ranges can change the behavior of scripts that rely on filelog output. This is because revision numbers of files "skip" or omit obliterated revisions. For example, the output of p4 filelog after obliterating revisions #2 and #3 might only have #4 and #1:
```
... #4 change 1276 edit on 2011/04/18 by user@dev1 (binary) 'Fixed'
... #1 change 1231 add on 2011/04/12 by user@dev1 (binary) 'First try'
```
In this case, if a script uses the #4 in the first line of the output to assume the existence of four change descriptions in the output of p4 filelog, the existence of only two change descriptions might affect the result of running the script.

The output of p4 filelog after purging revisions #1 and #2 (or a range including those revisions) might change from:

... #3 change 2123 edit on 2019/12/04 by user1@dev1 (binary) 'Third version'
... #2 change 2115 edit on 2019/12/03 by user1@dev1 (binary) 'Second version'
... #1 change 2101 add on 2019/12/01 by user1@dev1 (binary) 'First version'

to the following because actions, such as edit and add, for affected revisions are changed to purge:

... #3 change 2123 edit on 2019/12/04 by user1@dev1 (binary) 'Third version'
... #2 change 2115 purge on 2019/12/03 by user1@dev1 (binary) 'Second version'
... #1 change 2101 purge on 2019/12/01 by user1@dev1 (binary) 'First version'

Examples

`p4 obliterate dir/...`	Do not obliterate any files. Instead, list the files that would be obliterated with the `-y` option. In this case, all files in directory `dir` and below would be subject to deletion with the `-y` option. The output might be: `Would delete 3 client 3 revision ignoring 1 archived-revision record(s).` `This was report mode. Use -y to remove files. Add -A to include archived revisions.`
`p4 obliterate -A dir/...`	Do not obliterate any files. Instead, list the files that would be obliterated with the `-y` option and, because of `-A`, include any archived revisions. The output might be: `Would delete 3 client 3 revision 1 archived-revision record(s). This was report mode. Use -y to remove files.`
`p4 obliterate -y file`	Obliterate `file` from the depot. All history and metadata for every revision of `file` are erased.
`p4 obliterate -y file#3`	Obliterate only the third revision of `file`. If `#3` was the head revision, the new head revision is now `#2` and the next revision will be revision `#3`. If `#3` was not the head revision, the head revision remains unchanged.
`p4 obliterate -y file#3,5`	Obliterate revisions 3, 4, and 5 of `file`. If `#5` was the head revision, the new head revision is now `#2`, and the next revision will be `#3`. If `#5` was not the head revision, the head revision remains unchanged.

Related commands

To mark a file deleted at its head revision but leave it in the depot. This is the normal way of deleting files.	`p4 delete`
Instead of obliterating files, you can save disk space on a local depot by archiving some of its revisions to an archive depot. History of changes to these files is preserved.	`p4 archive`
To restore archived revisions from an archive depot. (You cannot restore obliterated files, but you can restore archived files.)	`p4 restore`