Building GitLens for VS Code

At the 2021 GitKon Git conference, Eric Amodio shared his journey for building GitLens, a VS Code app used by over 10 million developers worldwide. 

Long ago, Eric worked at a company building a WYSIWYG app for web development. While he had some version control experience, using tools like Microsoft Visual SourceSafe, Apache Subversion, (SVN), and Borland’s StarTeam, the team he was joining hadn’t used source control for their projects. Instead, they were just sharing files manually. 

As Eric joined, he pushed them to adopt SVN, which they struggled with. At the same time, Git was just coming out and starting to become an established player. As time passed, he and his team looked at a lot of distributed SCM tools, but as they compared Git vs SVN, they saw Git become the de facto leader. The fact that Git was open source and had a great community around it helped push them to migrate from SVN to Git. While there was a high learning curve, the power and versatility of Git made them glad they adopted it.

Encountering VS Code

Eric started out as a developer learning assembly language in school, which initially turned him off from programming. Then, he discovered Microsoft Visual Basic and fell in love. He felt enabled to bring things to life quickly, taking big ideas and making them a reality. 

From there, he moved on to .NET and watched as IDEs, like Visual Studio, were getting heavier and bigger. After dabbling with Sublime Text and other IDEs, VS Code premiered; and Eric thought it was beautiful. The open nature of parts of VS Code meant he could open up Dev Tools and just tweak the insides.

Early on, Eric found issues with some file sharing aspects of VS Code, among other things. He was able to debug the issues himself and sent an email off to the VS Code team with his patch. The very next day, his patch showed up in the VS Code release, which was his first of many positive experiences working with the VS Code community. 

Soon after, VS Code went completely open source and introduced an extension model. This was of major interest to Eric because instead of having to change the entire application to make it do what you wanted, like use TypeScript, you could add things on gradually. Basically, the code would meet you where you were.

The Idea for GitLens

Visual Studio had a system called CodeLens, which gave little annotations above the code in the IDE. These annotations described who authored the code and other various bits of metadata. VS Code exposed the CodeLens API and gave Eric the chance to play with various possible use cases. His first idea was to see if he could get information from Git to display in VS Code. And that’s how GitLens started, just playing with Git and VS Code to see what was possible.

GitLens’ tagline is: “GitLens supercharges the Git capabilities built into Visual Studio Code.” VS Code has its own built-in Git provider, which supports seeing and committing your changes. You can also create, view, and switch branches, but overall, VS Code is fairly limited when it comes to performing Git actions.

Eric wanted to expose a file’s Git history directly in VS Code. In-line code comments largely don’t exist for many developers. It is pretty rare that developers add explanations for their work inside the codebase to explain their choices and work. It leaves collaborators guessing why certain choices were made and what certain lines of code do.

However, those same developers often leave decent Git commit messages. The ability to walk back to see the historical record of how things got to be the way they are is pretty powerful. If you are not aware of how or why things got to a certain point, the risk increases for bugs and issues. 

This historical data is traditionally painful to dig out. Eric wanted to unlock the power inside Git repositories and get at this useful information, bringing it up to the forefront. That is the main goal of GitLens. To make it really easy to visualize your Git repository,  navigate your project history seamlessly, and be able to more easily locate things like specific commits. Eric really wants to help developers understand why things are the way they are now and how they changed over time.

It all started with a simple question: could someone get insights via CodeLens on any document? For example, could someone open a file, see who modified a file, and show exactly what changed, along with insights on why it was changed?

Eric believed that if the API allowed him to expose the Git commit messages around a line of code, then GitLens could really empower the developer. For example, if you are debugging your application and see a function that hasn’t changed in two years, that gives you a clue that maybe that’s not the place to look for the cause of a newly emerged problem. But if a function changed yesterday, maybe that is the right place to start debugging the new issue. 

GitLens and Solving Issues

Because you interact with GitLens through VS Code, you don’t have to context switch from editing your code to go interact with your Git repository. The information presented is contextually relevant to the lines of code you’re working on. Wherever your cursor is on the screen reveals who changed the selected line last, as well as expose the Git Diff for that line and show how long ago it was changed. 

All that relevant historical information is right in VS Code, meaning you don’t have to go off and look for it. It’s largely unobtrusive, staying in the background until you really want it. And when you do need it, it’s easy to surface, meeting you where you are, bringing a contextual view of your history to the code in the file you’re working in.

Eric also wanted to build up a richer client to bring insights to the whole repository, giving you the ability to see your branches and to dive into any Git branch and see the changes. He wanted to be able to see changes in real-time and compare commits, boiling down numerous changes to see just the set of files that have changed in a branch. This lets you quickly review and check to see what has changed over time. 

GitLens adds powerful capabilities to VS Code, allowing you to compare any two points from across a repository, without needing to context switch. 

GitLens and Git Merge Conflicts

Eric was motivated to make Git merge conflicts easier to resolve. While VS Code does provide some help with merge conflicts, more can be done. Currently, in cases of conflict, either from merging or rebasing, there is just not enough context given by default. GitLens provides info for each file, allowing you to easily see the diffs before a Git merge takes place. It can make it easy to see proposed changes and just pull in individual lines that address the given issue. 

The Future of GitLens

The future of GitLens is all about making the hard-to-use but powerful features of Git more accessible, such as merge conflict resolution and seeing the differences between branches. GitLens has the ability to visualize these features, but only in the tree view, separate from where you’re already looking. It can cause a bit of cognitive dissonance to try to connect the two different views, so Eric aims to bring those views closer together to further cut down on context switching. 

GitLens has buttons that allow you to navigate through a repo’s history and view previous commits. It can be confusing though if you are not sure exactly which commit or specific line of code you’re searching for. In the future, Eric wants GitLens to show something more meaningful than just the previous commit. This could include something like a timeline where you can see the ‘bigger bubbles’ for points in time where certain changes were made to a file. Ideally, this will let you quickly identify and jump between the most interesting points.

GitLens is also working to incorporate work trees. This is currently an obtuse feature of Git, but in the right circumstances, can be extremely valuable. If GitLens could offer multiple views and switch seamlessly between them, you could stash your changes and switch branches when you want to work on multiple things simultaneously. 

This is a hard problem for developers, who need to pause and then stash or reset their current work to go fix a bug or other issue that comes up. 

GitLens Features More People Should Leverage

Comparisons in GitLens are really important and, in Eric’s opinion, underused. Being able to see comparisons between different branches, or different points in time, and quickly review any sets of changes is extremely powerful. 

When reviewing Git pull requests you can look at each individual commit in the pull request, or you can look at the sets of files that have been changed as a whole. In GitLens, you can set up ad-hoc versions of the changed set view by just comparing any two points. From a single view, you can see the commits and sets of files that contain the committed changes. 

GitLens also has a Git command palette. VS Code has a command palette, where you can open and execute VS Code commands. GitLens has a Git command palette that lets you bring up and execute Git commands, providing a guided experience. For example, if you want to create a Git branch:

1. Open the command palette
2. Type and select git branch and then select the create option.
3. Pick which repo and which branch that you want to create the new branch from
4. Add the name of the new branch and VS Code creates it for you.

The GitLens command palette gives a nice guided tour through Git commands exposing the different options available.

Building GitLens for VS Code

The VS Code API is intentionally locked down to make sure it’s robust and can stand the test of time, without causing negative impacts on performance. The VS Code team has spent a lot of time expanding the capabilities of the API over the years, and the interface is getting easier to work with. Now, you can host web views and control the UI and the UX yourself, moving beyond the locked down view VS Code originally offered.

When getting started with VS Code, it is important to realize that there may be certain challenges. There are still limits on the API’s capabilities. You should check out if APIs already exist for your areas of interest as you are getting started. This can help you avoid frustrations over misconceptions around how the API accomplishes certain things. Given a smaller API surface area resulting from its locked-down nature, you have to get creative in the ways that you put the building blocks together. You can build some really interesting and powerful things once you fully understand how things really work and where the limits are. 

The API has powerful tools for building things like the VS Code file system abstractions. These abstractions let you build really rich elements, which is what GitLens relies on to build the file abstraction on top of Git. By going to a specific, structured URI for a particular file in history, GitLens can then leverage the whole file system. There’s a lot of power built into these APIs that let you envision just about anything, and the constraints are very helpful to help you understand what you can do. They also ensure that what you implement is nice and performant, making you think about the UX along the way.

Get Involved with GitLens and VS Code

For those looking to get involved in the GitLens and VS Code community, Eric runs a Slack community for extension authors. All are welcome to join, ask questions, and meet other authors, which is a good way to get started with VS Code contributions and find possible examples of what you want to do. Asking questions and playing around with the VS Code API is a great way to find your way, as it’s pretty accessible, easy to debug, and use.

There is even a Yeomen generator for VS Code that will scaffold out a project for you. This lets you quickly get through setup, and can help debug and test things out quite easily. 

The Future of Git is Visual

According to Eric, the future of Git is better visualization. You can jump to the end of his talk to hear more of his thoughts on the future of Git and the tech industry overall. 

Shortly after GitKon, GitKraken acquired GitLens and Eric joined GitKraken as the new Chief Technology Officer to lead the continued development of GitLens and GitKraken’s popular Git client. By teaming up with GitKraken, Eric is now focused on GitLens full-time and GitLens gained the full support and resources of a leading software company that specializes in Git collaboration and productivity solutions for development teams.

Download the free GitKraken Git client to leverage the power of a visual Git GUI and CLI on your desktop, and install GitLens for free to access the power of Git in VS Code.