Context Buddy

Michał Bednarz
Apr 17, 2020 · 6 min read
Image for post
Image for post
Photo by João Silas on Unsplash

History matters

At some point in your work as a software engineer, history-related questions arise. Consider a typical source file that has been modified many times since its creation. The original intent of the authors has been lost under multiple layers of changes introduced over time. Despite the difficulties, we want to understand the original idea as well as the reason behind particular changes.

What tools could we use to streamline the process of understanding the codebase?

git blame to the rescue

Often we boil down the problem of understanding the codebase to some concrete questions about a particular fragment of code. Namely, in which commit was this fragment introduced? What is the message and author of that commit? These questions can be easily answered with the help of git blame. In many cases, git blame (or a corresponding feature in the IDE) is enough. git blame is line-based, so we can see that the given line was affected by the particular commit — but what about an individual token (method, parameter or variable)? Of course, you can keep drilling down the history with git blame to find out why the given parameter was added, but this takes time. Similar questions remain: who, why and when introduced or modified the given token?

Meet your Buddy

Context Buddy helps to solve exactly that problem: token-based history. Let’s have a look at its concrete use case so that we can see the tool in action. For the sake of this example, we are going to use Buddy’s Visual Studio Code extension, but the functionality of the IntelliJ IDEA plugin is very similar. The example code is actually an existing GitHub action that is used to provide more advanced features that will be introduced in the future and described in the next articles. Understanding how that code works is not required for the purposes of this article. We will examine just the history of changes applied to it.

Let’s start with the following snippet:

Image for post
Image for post

Assuming that the git repository already exists, let’s commit the file to the version control using git add and git commit commands. At this moment we can already use Context Buddy! To do this, install the Context Buddy Extension which can be found in Visual Studio Marketplace.

Now click the “Enable Context Buddy” button in the plugin tree view.

Image for post
Image for post

We can see that each token is highlighted with the same color. Moreover, when you hover the mouse over a token, a tooltip appears with the information about the last commit that modified it. To see the power of the plugin, we are going to introduce some changes. Let’s take a look at the next version of the file:

Image for post
Image for post

As you can see, the second commit has introduced a bunch of additions. How does this version of the file relate to the initial one? Which tokens have been added or modified in the second commit? This is the moment when the advantage of Context Buddy over git blame becomes clear.

Image for post
Image for post

How does the tool respond to the new changes? If the visible tokens come from different commits, each commit is highlighted by a different color.

In our next example, we are going to see how the file is highlighted after three commits. Let’s proceed to the working example at once:

Image for post
Image for post

At this point, it is useful to start using extra visual features provided by Context Buddy. Click at one of the listed commit contexts to make it clear which fragments of code correspond to the given point in history. In addition, you can start to experiment with various color options and settings. The above examples provide a different color for each individual commit but the code can as well be highlighted according to the author. It is worth noticing that in our example all changes were introduced by one person, but options like that start to become more useful as your team, as well as the history of your repository grows.

In conclusion, let’s have a look at another example that demonstrates how Context Buddy handles more complex commit history. This is a file from the falcon open-source project.

Image for post
Image for post

Other relevant applications

The examples show that the tool is very useful even in simple cases. It provides granular and clear insight into the history of our code. However, its real strength comes to light in more complicated situations.

One such situation is the aftermath of a code formatting change throughout the project. After such a change, the information provided by git blame becomes useless. Context Buddy though preserves the relevant information thanks to tracking the changes for code tokens rather than lines. Reformatting does not have any unwanted impact on our history anymore.

Under the hood

How does Context Buddy actually work? To understand the mechanism behind the tool we can start with another question — how does git diff actually compare the versions of files? It does it line by line. Here is an excerpt from the commit diff of the previous example.

Image for post
Image for post

Git recognizes this change as the deletion of a line and the addition of another line. The “name” token though, has not changed at all. This fact is lost by git but recognized by Context Buddy. How is it done?

Context Buddy splits a file into tokens (according to the language or file format) and tracks each token and its position in a file separately. Let’s look at our example:

Image for post
Image for post

Starting with the above fragment of code — it will be tracked like this:

Image for post
Image for post

When changed to:

Image for post
Image for post

Transformed fragment of code will be represented as follows:

Image for post
Image for post

Context Buddy takes a fragment of code from the “Token” column and updates information about its position. Values in the “Position” column correspond to line start, line end, column start, and column end. Buddy will use the context of the latest commit in which the token has been changed.

Language support

Identification and localization of tokens in the source code is a process that is unique for the grammar of a language. This is why Context Buddy requires explicit support for each programming language. Current implementation covers a pretty wide range of popular file formats. The list of supported file extensions can be found here in the documentation. Feel free to create an issue if you would like Buddy to support any other language.

Much more is about to come

History tracking for each individual token is the place where we start — a building block for more advanced features. Our goal is to reveal the information that has been hidden and unavailable so far. We are going to retrieve and process pull request review comments, semantic changes and even test results or production incidents from your remote repository and link them with source code. We are going to release and introduce these ideas in the near future — stay tuned for the updates!

Get it and start using it

For now, Context Buddy is available for IntelliJ IDEA and Visual Studio Code. Both plugins are available within their respective VS Code and IntelliJ IDEA marketplaces. If you find the tool useful and have any feature request, please feel welcome to create an issue in our public repository.

VirtusLab

Virtus Lab company blog

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store