Working with Annotations
Annotation is a form of file presentation that shows detailed information for each line of code. In particular, for each line you can see the version from which this line originated, the user ID of the person who committed this line, and the commit date. The annotated view helps you find out who did what and when, and trace back the changes.
Annotating lines of code is available for ClearCase, TFS, Mercurial, Git, CVS, Perforce and Subversion.
The Annotate command appears in the VCS-specific nodes of the Version Control menu, file context menus, and the File History view. This command toggles between the plain and the annotated view of a file.
In this topic:
- Showing and hiding annotations
- Configuring the amount of information shown in the annotations pane
- Annotating previous revisions
- Viewing differences between revisions
Showing and hiding annotations
- Open the desired file in the editor.
To show annotations, right-click the left gutter, and select Annotate:
When annotations are enabled, the left gutter looks similar to the following example:
The annotations pane provides the following information:
- The number of the changelist within which the annotated change was checked in.
- The date when the annotated change was checked in.
- The name of the user who checked in the annotated change.
- The revision number of the current file.
- To hide annotations, right-click the annotations gutter, and choose .
Configuring the amount of information shown in the annotations pane
- Enable annotations and right-click the annotations gutter.
Select View in the context menu and enable or disable the following options according to
the type of information you want to be displayed:
- Revision: select this option if you want to see the number of the changelist within which the annotated changes were checked in.
- Date: select this option if you want to see the date when the annotated changes were checked in.
- Author: select this option if you want to see the name of the user who checked in the annotated changes.
- Commit number: select this option if you want to see the revision number of the current file.
Colors: use this control to toggle between the following highlighting modes:
- Author: select this option if you want to highlight changes made by different authors with different colors:
- Order: select this option if you want annotation colors to indicate how recently a change was made. The entire file history is divided into several time periods containing an equal number of commits, and each time period is assigned its own color. The most recent changes are highlighted with green, while the oldest changes are highlighted in red:
- Hide: select this option if you do not want to use any color highliting. In this case, all annotations will be displayed in gray.
Names: use this control to select how user names will be presented. The following options
- Last name
- First name
- Full name
To view a commit message for an annotated change, hover the mouse cursor over an annotation.
A tooltip will appear showing the commit message for the corresponding change:
Note that the amount of information displayed in the tooltip depends on the version control system you are using and is not affected by the annotation settings.
Annotating previous revisions
PhpStorm lets you annotate not only the current revision of the file, but also it's previous revisions. The following options are available:
- Annotate Revision: this option is useful if you want to check what a file looked like after a particular change was committed. To do this, right-click this change and select Annotate Revision from the context menu.
- Annotate Previous Revision: this option is useful if you find yourself in a situation when the last change in a particular line is meaningless, for example if all that was changed is code formatting. In this case, you can check what the previous revision of the file looked like. To do this, right-click a change and select Annotate Previous Revision from the context menu.
You can also annotate a particular file from the file history view. In the History tab, select the file version you want to review, right-click the corresponding line and select from the context menu.
Viewing differences between revisions
Position the cursor on an annotation, right-click it and select Show Diff from the context menu. PhpStorm opens the Differences viewer for files where you can view what changed between the annotated revision of the file and its previous revision: