How to Use

If you have any problems using Azurite, or any suggestions on how to improve this tool,
please contact YoungSeok Yoon with detailed information.

Installing the plug-in

In order to use Azurite, you must have JRE 7 or higher installed.

WINDOWS USERS: Azurite requires Internet Explorer 9 or higher to display the timeline correctly.

To install Azurite plug-in to your Eclipse environment, please follow the instructions below.

Click the "Help -> Install New Software..." menu item.

Click the "Add..." button.

Fill out the boxes as below, and hit "OK".
Name: Natural Programming
Location: http://www.cs.cmu.edu/~NatProg/eclipse/updates/releases/

Check "Azurite for Eclipse" under "Natural Programming Project" category and click "Next".
(NOTE: Fluorite will be automatically installed together, even if you don't explicitly select it.)

Follow the instructions shown in the dialog.

back to top

Updating the plug-in

Click the "Help -> About" menu item.

Click the "Installation Details" button.

Select the "Azurite for Eclipse" item from the list, and click "Update" at the bottom.
(If "Fluorite Event Logger for Eclipse" shows up in the list, then please select it together.)

back to top

Uninstalling the plug-in

Click the "Help -> About" menu item.

Click the "Installation Details" button.

Select the "Azurite for Eclipse" item from the list, and click "Uninstall" at the bottom.

back to top

Using the Timeline View

One of the most important features of Azurite is the timeline view. To open the timeline view, click "Window -> Show View -> Other... -> Azurite -> Timeline View"



The resulting screen would look like above. The timeline visualization is shown at the bottom. Whenever an edit operation (insertion, deletion, or replacement) is performed on the code editor, a rectangle representing that edit is added at the end of the timeline. Insert, Delete, and Replace operations are color-coded as green, red, and blue, respectively.

The horizontal location and width of a rectangle represents the time and duration of the edit performed. The vertical location and height of a rectangle within the row represents the relative location of the edit within the file. There is a minimum width and height of a rectangle so that users can easily identify or select even small edits. Each row in the timeline corresponds with each file being edited in the code editor.

Whenever you make a new edit to a file, a new rectangle immediately appears at the right end of the timeline view representing that edit. By default, the most recently edited file moves to the top row automatically; this enables the user to quickly recognize the most recently edited files by reading the file names from top to bottom.

Note that unlike the undo stack, the edit history contains all the edits that have ever been performed, in chrronological order. Any undo operations are added on to the end of the timeline, just like any other operation, and the operation which was undone is still kept in the visualization. This makes it possible to see all previous operations and states of the files.


More detailed information of each edit is shown as a tooltip which is shown on mouse hover (see above). The tooltip contains the exact time when the edit has made, and the text that was inserted and/or deleted by that edit.

A rectangle can be double-clicked to open the file in code editor and move the cursor to the location in the file where the operation was performed.

back to top

Layout Modes

Azurite's timeline visualization supports two layout options: real-time mode and compact mode. You can switch between the two modes by clicking the "Compact Mode" button.

In real-time mode, the rectangles are horizontally located proportionally to the actual time that they were made. However, there is a significant problem with this approach. There are many gaps between the changes because developers use only about 20% of their time actually editing code, which makes it difficult to navigate through the edit history in the timeline.

To resolve this problem, Azurite provides a compact mode, which is used by default. In compact mode, all the horizontal gaps between rectangles are removed so that times when you are not editing are not displayed, and all the edits are shown contiguously.

We kept the real-time mode as an option because it can be useful in some situations. For instance, you could better re-construct your previous working context by seeing the size of the gaps and grouping the edits temporally. You can switch between the two modes at any time.

back to top

Selecting Changes and Invoking Commands

Edit operation(s) can be selected manually by clicking the rectangles or dragging an area (Ctrl+Click to select multiple items). Alternatively, multiple operations can be selected by edit history search feature.

When a single operation is selected
When multiple oprations are selected

Once some operations are selected, you can invoke a popup context menu by right-clicking on the timeline. The context menu provides useful commands such as "Selective Undo". This command selectively undoes the selected edit operations while keeping the effects of the other edits.

back to top

Searching for Edit Operations

Azurite supports edit history search, which allows users to easily search through code edit history and select multiple operations at once. First, Azurite supports "Select Operations in Selected Region," where users can highlight a certain area of code and select all the edit operations performed in the past which affected that area. This menu can be found under "Azurite" in the menu bar, or in the context-menu.

Another option is to use the "History Search" dialog, which can be found under "Azurite" menu.

Using this dialog, you can search for all edits that happened during a time interval where a certain code (or text) existed. Note that the searched-for text does not necessarily have to exist now in the code, so this is not the same as searching the current code base for the text. For example, you can search for DrawRectangle when the code now says PaintRectangle and an operation is "replace Draw with Paint".

back to top

Using the Code History Diff View


The code history diff view is shown above. You can select an arbitrary code snippet from the code editor and launch this view, which is a code-compare view with two juxtaposed panels. The left-hand panel shows some version of the code in the past along with the version number, and the exact time when the change was made. The right-hand panel always shows the current version (i.e., the most recent version) of the code snippet. The diffs between the two code snippets are marked. The left side code can go all the way back to when the code did not even exist, assuming that this is in the history.

You can move back and forth through the history in two ways. First, you can drag the marker within the timeline with mouse to see how the code looked at the time at which the marker is pointing. The marker is a red vertical line as shown above, which appears in the timeline when a code history diff view is shown. This design was inspired by the time marker in video editors. The code snippet shown on the left panel changes instantaneously as the marker is moved, and diffs are recalculated as well. Alternatively, users can use the navigation buttons above the code to move back and forth through different versions incrementally. This is useful when there are many rectangles in the timeline between versions, which are irrelevant to the code snippet that the user is interested in. Whenever the version changes using the navigation buttons, the marker position in the timeline is also updated correspondingly.

The code history diff view can be used for several different purposes. First, it can be used to simply understand how the code has evolved. In addition, this view can be used to look for some deleted code and copy the code to reuse it in the current code. Finally, users can revert the code snippet to one of its previous versions simply by moving to the desired version and clicking the "Revert" button.

back to top

Reviewing the History of a Code Fragment

You might have the following questions during development:

  • When, how was this code changed or inserted?
  • How has it changed over time?
  • Has this code always been this way?
These questions can be easily answered by selecting the code and launching the code history diff view.

back to top

Determining What Recent Changes Were Made

Developers can load the history of the past editing session to see what recent changes have been made to the project. Since the most recently changed file is always shown at the top in the timeline, the recently changed files can be easily identified by reading the file names from the top. If more detailed information is needed, the user can jump to the specific code by double-clicking the last rectangle of each file and the code history diff can be viewed if necessary to see the actual code edits.

back to top

Reverting LayoutManager to a Previously Used One

When programming graphical user interfaces (GUIs), one often ends up having to experiment with different layout managers to get the UI to look as desired. Imaging the following scenario: You are implementing a GUI dialog in Swing. You first write the code with GridBagLayout, and then changes to a simpler BoxLayout manager because of the complex parameters of GridBagLayout. Then you realize BoxLayout does not look very pretty, and wants to revert back to GridBadLayout.

This can be done using Azurite by searching for the time when GridBagLayout existed in the code snippet, and then reverting the code to the desired version with "undo everything after selection" command or "revert" button in the code history diff view. Note that this works even if other, unrelated changes are made after or interspersed with the edits to the layout manager, which would make using conventional undo or a version control system inappropriate.

back to top

Removing Temporary Debugging Code

One popular debugging strategy is to add print or logging statements in various locations to see how the values change as the program executes. In many cases, these statements are temporary and should not be committed to the main repository. Removing all the recently added println statements, however, can be a tedious task if they are spread across multiple locations. If the println statements were consecutive in the history (i.e., they were inserted at the same time), this can be done relatively easily with Azurite.

First, you can locate one of the println statements from the code editor with regular search, for example. Then, you can identify the point in time when the statement was inserted with history search or code history diff view. Since all the println insertions would appear near to each other in the timeline, they can be easily selected together and undone at once. This works even if there are other println statements mixed in the code that were not part of this debugging and thus should be kept unchanged, in which case regular text search would be less useful.

back to top

Sending the Log Files

To send your log files to the experimenter, please follow the steps below.

  1. If your Eclipse is currently running, please close it before collecting the log files.
  2. Go to the log files directory ( "[Your Eclipse Workspace]/.metadata/.plugins/edu.cmu.scs.fluorite/Logs" )
  3. Archive all the log files in there as a zip file.
  4. If you have multiple Elipcse workspaces, please do the same (steps 2 & 3) for each workspace you used since the logging plug-in was installed.
    NOTE: Be sure to exclude the workspaces that you do not want to share. (e.g., confidential code)
  5. Please send an email to the experimenter with the zip file(s) attached.
    (YoungSeok Yoon: youngseok (at) cs.cmu.edu)

back to top