A snapshot of a file at a specific point in time.


@interface NSFileVersion : NSObject


Use the methods of this class to access, create, and manage file revisions in your app.

Each file version instance contains metadata about a single revision, including the location of the associated file, the modification date of the revision, and whether the revision is discardable.

In Mac apps, you can use file version objects to track changes to a local file over time and to prevent the loss of data during editing. When managing local versions, the document architecture creates versions at specific points in the lifetime of your application. Your application can also create versions explicitly at times that your application designates as appropriate.

In addition to managing local files, the system also uses this class to manage cloud-based files. For files in the cloud, there is usually only one version of the file at any given time. However, additional file versions may be created in cases where two different computers attempt to save the file to the cloud at the same time. In that case, one file is chosen as the current version and any other versions are tagged as being in conflict with the original. Conflict versions are reported to the appropriate file presenter objects and should be resolved as soon as possible so that the corresponding files can be removed from the cloud.


Getting the Version of a File

+ currentVersionOfItemAtURL:

Returns the most recent version object for the file at the specified URL.

+ otherVersionsOfItemAtURL:

Returns all versions of the specified file except the current version.

+ versionOfItemAtURL:forPersistentIdentifier:

Returns the version of the file that has the specified persistent ID.

+ temporaryDirectoryURLForNewVersionOfItemAtURL:

Creates and returns a temporary directory to use for saving the contents of the file.

Creating a New Version

+ addVersionOfItemAtURL:withContentsOfURL:options:error:

Creates a version of the file at the specified location.

Accessing the Version Information


The URL identifying the location of the file associated with the file version object.


The string containing the user-presentable name of the file version.


The user-presentable name of the computer on which the revision was saved.


The modification date of the version.


The identifier for this version of the file.


A Boolean value that specifies whether the system can delete the associated file at some future time.

Handling Version Conflicts


A Boolean value indicating whether the contents of the version are in conflict with the contents of another version.


A Boolean value that indicates the version object is not in conflict (YES) or is in conflict (NO).

+ unresolvedConflictVersionsOfItemAtURL:

Returns an array of version objects that are currently in conflict for the specified URL.

Replacing and Deleting Versions

- replaceItemAtURL:options:error:

Replace the contents of the specified file with the contents of the current version’s file.

- removeAndReturnError:

Remove this version object and its associated file from the version store.

+ removeOtherVersionsOfItemAtURL:error:

Removes all versions of a file, except the current one, from the version store.



Options for adding a new file version.


Options for replacing a file version.


Inherits From

See Also

Managed File Access


An object-oriented wrapper for a file descriptor.


A stub class that encapsulates security information about a file.


A representation of a node (a file, directory, or symbolic link) in the file system.