Context Buddy
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:
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.
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:
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.
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:
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.
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.
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:
Starting with the above fragment of code — it will be tracked like this:
When changed to:
Transformed fragment of code will be represented as follows:
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.
