From d4a58763d03a726eb9db62727d2bd59b23b0e7f8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yann=20C=C3=A9bron?= Date: Mon, 9 May 2022 15:32:22 +0200 Subject: [PATCH] vcs_integration_for_plugins.md: cleanup --- .../vcs_integration_for_plugins.md | 51 +++++++++---------- 1 file changed, 23 insertions(+), 28 deletions(-) diff --git a/topics/reference_guide/vcs_integration_for_plugins.md b/topics/reference_guide/vcs_integration_for_plugins.md index 4b2f889ae..29d13f332 100644 --- a/topics/reference_guide/vcs_integration_for_plugins.md +++ b/topics/reference_guide/vcs_integration_for_plugins.md @@ -11,7 +11,7 @@ Reference: [OSS plugins providing VCS](https://jb.gg/ipe?extensions=com.intellij ### FilePath A [`FilePath`](upsource:///platform/ide-core/src/com/intellij/openapi/vcs/FilePath.java) represents a path to a file or directory on disk or in the VCS repository. -Unlike a [`VirtualFile`](upsource:///platform/core-api/src/com/intellij/openapi/vfs/VirtualFile.java), a `FilePath` can represent a path to a file which doesn't exist on disk. +Unlike a [virtual file](virtual_file.md), 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`](https://docs.oracle.com/javase/8/docs/api/java/io/File.html) 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`](upsource:///platform/vcs-api/src/com/intellij/openapi/vcs/actions/VcsContextFactory.java) API is used. @@ -38,8 +38,8 @@ It has three main attributes: 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. +Revisions of binary files can also be represented as [`BinaryContentRevision`](upsource:///platform/vcs-api/src/com/intellij/openapi/vcs/changes/BinaryContentRevision.java). +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 [`CurrentContentRevision`](upsource:///platform/vcs-api/src/com/intellij/openapi/vcs/changes/CurrentContentRevision.java). @@ -53,13 +53,13 @@ It determines the color used to render the name of the file in the UI. A [`Change`](upsource:///platform/vcs-api/vcs-api-core/src/com/intellij/openapi/vcs/changes/Change.java) 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`](upsource:///platform/vcs-api/vcs-api-core/src/com/intellij/openapi/vcs/changes/Change.java) essentially consists of two content 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) +* 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`](upsource:///platform/vcs-api/vcs-api-core/src/com/intellij/openapi/vcs/changes/Change.java) if it represents a non-standard modification of the file (for example, a file which has been merged with conflicts). +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. ### ChangeList @@ -68,12 +68,11 @@ A [`ChangeList`](upsource:///platform/vcs-api/src/com/intellij/openapi/vcs/chang There are two main kinds of changelists: * [`LocalChangeList`](upsource:///platform/vcs-api/src/com/intellij/openapi/vcs/changes/LocalChangeList.java) 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. + If the VCS also supports the concept of changelists (like Perforce does), the VCS plugin can synchronize the IDE'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. * [`CommittedChangeList`](upsource:///platform/vcs-api/src/com/intellij/openapi/vcs/versionBrowser/CommittedChangeList.java) 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`](upsource:///platform/vcs-api/src/com/intellij/openapi/vcs/versionBrowser/CommittedChangeList.java) + 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`. > The Unversioned Files, Locally Deleted Files, etc., nodes in the Changes view are not actually change lists, and files under those nodes are not represented by `ChangeList` objects. > @@ -86,7 +85,7 @@ This section describes the different components which comprise a VCS integration ### AbstractVcs This is the main entry point for a VCS plugin, which is used by the IntelliJ Platform 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: +Register `AbstractVcs` implementation in `com.intellij.vcs` extension point in plugin.xml, as shown in the following example: ```xml @@ -97,41 +96,37 @@ The recommended way to register an AbstractVcs implementation is to add an exten ``` -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. +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. ### ChangeProvider -This component is responsible for tracking user changes to the working copy, and reporting these changes to the IntelliJ Platform core. +[`ChangeProvider`](upsource:///platform/vcs-api/src/com/intellij/openapi/vcs/changes/ChangeProvider.java) is responsible for tracking user changes to the working copy, and reporting these changes to the IntelliJ Platform core. An implementation of this class is returned from [`AbstractVcs.getChangeProvider()`](upsource:///platform/vcs-api/src/com/intellij/openapi/vcs/AbstractVcs.java). The ChangeProvider works in tandem with [`VcsDirtyScopeManager`](upsource:///platform/vcs-api/src/com/intellij/openapi/vcs/changes/VcsDirtyScopeManager.java) -, which is a component in IntelliJ Platform core. -[`VcsDirtyScopeManager`](upsource:///platform/vcs-api/src/com/intellij/openapi/vcs/changes/VcsDirtyScopeManager.java) -keeps track of the 'dirty scope' - the set of files for which the VCS file status may be out of date. +. +It keeps track of the 'dirty scope': the set of files for which the VCS file status may be out of date. Files are added to the dirty scope either when they are modified on disk, or when their VCS status is invalidated by an explicit call to [`VcsDirtyScopeManager.fileDirty()`](upsource:///platform/vcs-api/src/com/intellij/openapi/vcs/changes/VcsDirtyScopeManager.java) or [`VcsDirtyScopeManager.dirDirtyRecursively()`](upsource:///platform/vcs-api/src/com/intellij/openapi/vcs/changes/VcsDirtyScopeManager.java). -After some files have been added to the dirty scope, the dirty scope is passed to -[`ChangeProvider.getChanges()`](upsource:///platform/vcs-api/src/com/intellij/openapi/vcs/changes/ChangeProvider.java), along with a +After some files have been added to the dirty scope, the dirty scope is passed to `ChangeProvider.getChanges()`, along with a [`ChangelistBuilder`](upsource:///platform/vcs-api/src/com/intellij/openapi/vcs/changes/ChangelistBuilder.java) -instance, which serves as a sink to which the -[`ChangeProvider`](upsource:///platform/vcs-api/src/com/intellij/openapi/vcs/changes/ChangeProvider.java) -feeds the data about the changed files. +instance, which serves as a sink to which the `ChangeProvider` feeds the data about the changed files. This processing happens asynchronously in a background thread. -The [`ChangeProvider`](upsource:///platform/vcs-api/src/com/intellij/openapi/vcs/changes/ChangeProvider.java) can either iterate all files under the dirty scope using +The `ChangeProvider` can either iterate all files under the dirty scope using [`VcsDirtyScope.iterate()`](upsource:///platform/vcs-api/src/com/intellij/openapi/vcs/changes/VcsDirtyScope.java) , or retrieve information about its contents using the `getDirtyFiles()` and `getDirtyDirectoriesRecursively()` methods. If it is possible to retrieve the information about the local changes from the VCS in batch, it's strongly preferable to use the second method, as it scales much better for large working copies. -The [`ChangeProvider`](upsource:///platform/vcs-api/src/com/intellij/openapi/vcs/changes/ChangeProvider.java) reports data to ChangelistBuilder using the following methods: +The `ChangeProvider` reports data to `ChangelistBuilder` using the following methods: * `processChange()` is called for files which have been checked out (or modified if the VCS doesn't use an explicit checkout model), scheduled for addition or deletion, moved or renamed. -* `processUnversionedFile()` is called for files which exist on disk, but are not managed by the VCS, not scheduled for addition, and not ignored through *.cvsignore* or a similar mechanism. +* `processUnversionedFile()` is called for files which exist on disk, but are not managed by the VCS, not scheduled for addition, and not ignored through .cvsignore or a similar mechanism. * `processLocallyDeletedFile()` is called for files which exist in the VCS repository, but do not exist on disk and are not scheduled for deletion. -* `processIgnoredFile()` is called for files which are not managed by the VCS but are ignored through *.cvsignore* or a similar mechanism. +* `processIgnoredFile()` is called for files which are not managed by the VCS but are ignored through .cvsignore or a similar mechanism. * `processSwitchedFile()` is called for files or directories for which the working copy corresponds to a different branch compared to the working copy of their parent directory. - This can be called for the same files for which processSwitchedFile() has already been called. + This can be called for the same files for which `processSwitchedFile()` has already been called.