This page gives an overview of the Version Control Integration API in IntelliJ IDEA 7.0. Most of the concepts described here also apply to IntelliJ IDEA 6.0. The VCS API was significantly refactored in version 6.0, and this document does not describe the API of older versions.
A FilePath (com.intellij.openapi.vcs.FilePath) represents a path to a file or directory on disk or in the VCS repository. Unlike a VirtualFile, a FilePath can represent a path to a file which doesn't exist on disk. The main difference between a FilePath and a java.io.File is that a FilePath caches the VirtualFile corresponding to the path, so it can be retrieved without doing a VFS search.
To create instances of FilePath, the VcsContextFactory API is used. It can be accessed as PeerFactory.getInstance().getVcsContextFactory().
FilePaths representing paths in a VCS repository, rather than local paths, are created using VcsContextFactory.createFilePathOnNonLocal(). FilePath.isNonLocal() returns true for such files.
A VcsRevisionNumber (com.intellij.openapi.vcs.history.VcsRevisionNumber) represents a revision number of the file. If the VCS stores revision numbers as simple integers, the standard VcsRevisionNumber.Int implementation can be used. If the VCS has a more complex format of revision numbers (like CVS, which uses a series of numbers delimited with dots), the plugin can provide a custom implementation.
A ContentRevision (com.intellij.openapi.vcs.changes.ContentRevision) represents a particular revision of a file, which exists either locally or in a VCS repository. It has three main attributes:
- FilePath specifying the file of which this is a revision. If some version of the file exists locally, this should be a local path.
- VcsRevisionNumber specifying the revision number of the revision, or VcsRevisionNumber.NULL if the revision exists only locally.
- Content of the revision.
The content is returned as string, and the VCS plugin is responsible for converting the binary file content to correct encoding. To detect the encoding automatically based on the IDE settings and the byte order mark, the method CharsetToolkit.bytesToString() can be used (this API is new in IDEA 7.0.2). Revisions of binary files can also be represented as BinaryContentRevision, which is a subclass of ContentRevision. For binary revisions, the result of getContent() is undefined, and getBinaryContent() can be used to retrieve the contents as a byte array.
A useful class which can be used to represent the current on-disk version of a particular file is com.intellij.openapi.vcs.changes.CurrentContentRevision.
A FileStatus (com.intellij.openapi.vcs.FileStatus) represents a status of a file in regard to VCS (unversioned, not changed, added, modified and so on). It determines the color used to render the name of the file in the UI.
A Change (com.intellij.openapi.vcs.changes.Change) represents a single file operation (creation, modification, move/rename or deletion) from a VCS point of view. A Change can represent either a modification which the user has performed locally and not yet committed, a committed modification, or some other type of modification (for example, a shelved change or a difference between two arbitrary revisions).
A Change essentially consists of two content revisions:
- before revision (null if the Change represents file creation);
- after revision (null if the Change represents file deletion).
A move or rename is represented by a Change where the before revision and the after revision have different file paths.
A custom file status can be specified for a Change if it represents a non-standard modification of the file (for example, a file which has been merged with conflicts). If a custom file status has not been specified, the status is calculated automatically from the change type.
A ChangeList (com.intellij.openapi.vcs.changes.ChangeList) represents a named group of related changes. There are two main kinds of changelists:
- Local (LocalChangeList) represents a group of modifications done by a user locally. If the VCS also supports the concept of changelists (like Perforce does), the VCS plugin can synchronize IDEA's local changelist structure with that of the VCS. Otherwise, a local changelist is simply a subset of the files checked out or modified by the user.
- Committed (CommittedChangeList) represents a set of modifications checked in to the VCS repository. For VCSes which support atomic commit, every committed revision is represented by a CommittedChangeList. For VCSes which use per-file commit (like CVS), the plugin can use heuristics to group a sequence of individual file commits into a CommittedChangeList.
This section describes the different components which comprise a VCS integration plugin, roughly in the same order as they should be implemented.
This is the main entry point for a VCS plugin, which is used by IntelliJ IDEA to retrieve all other services provided by the plugin. The recommended way to register an AbstractVcs implementation is to add an extension declaration to plugin.xml, as shown in the following example:
<idea-plugin version="2"> ... <extensions defaultExtensionNs="com.intellij"> <vcs name="svn" vcsClass="org.jetbrains.idea.svn.SvnVcs"/> </extensions> </idea-plugin>
Here 'name' is the unique name of the VCS (this must match the string returned by your implementation of AbstractVcs.getName()), and 'vcsClass' is your implementation class.