How to use Git in the Eclipse Theia IDE

This  series of articles  describes how to get started with the Eclipse Theia IDE. In this particular article, we provide an overview about  the Git support of the Eclipse Theia IDE. Please see previous articles on how to launch Theia, or how to use the Theia IDE and for a quick introduction of Theia.

The default Git support in the UI of Eclipse Theia is quite minimalistic, but it is a good reflection of what many developers do today anyway: using a mixture of some UI features and executing additional commands on the command line. It is also very similar to Git support in VS Code so many of you probably  feel familiar with it. The Theia Git extension focuses on use cases, which benefit from a UI support. This mainly includes support for staging, committing, browsing history and comparing files.

In Eclipse Theia, there are currently four places, where you can interact with Git:

1. The “SCM view”: For staging, comparing, committing, resetting, amending and related use cases
2. The “History View”: for browsing and interacting with the Git history
3. Git Commands: The commands bar (press “F1”) provides quite a few Git commands such as “Git clone” or “Git checkout” as quick access actions
4. The Terminal: Provides full access to all Git commands

So let’s walk through a typical scenario using Git in Eclipse Theia. In the following we will focus on Git commands, which are provided in the SCM view, the history view or as commands. Commands can be executed by pressing “F1” and typing the name of the command (auto-completion is supported). All described, use cases can alternatively be executed in the terminal view in Theia as well, just like in a regular terminal.

Git Init

If you want to initialize a Git repository locally, you can do so, by opening the “SCM View” and clicking on the “+” button at the top right. This will initialize a Git repository using the workspace folder as a root. Alternatively, you can achieve - the same by using the command by pressing “F1” and type “Git: Initialize Repository”

Git Clone

To clone a Git repository, use the command “Git:clone…”. The three dots at the end of a command indicate, that there are some additional parameters required to execute this command. In this case, the additional parameter is the repository URL, Theia will open a popup input field to enter that. On Enter, Eclipse Theia will clone the corresponding repository into the workspace and checkout master by default.

Git Stage / Add to index / Discard

Staging modified files as well as adding new files to the index is well supported via the SCM view. The view shows you a list of all modified files (marked with an “M”) and unstaged files (marked with an “U”). Via the “+” button next to the file, you can stage those changes and add new files to the index, respectively. The circle button next to the “+” allows you to discard a specific change (or delete a new file). A double-click on a modified file will directly open a comparison between the working tree and the index version of the corresponding file. Finally, you can unstage files again by clicking the “-” button. As a shortcut, there are also commands available for staging, e.g. “Git: Stage all changes” or “Git: Discard all changes”. The same options can be found in the “…” menu in the top right corner of the SCM view.

Git Commit / Amend

Commit is done by entering a commit message and pressing “CTRL+ENTER”. You might prefer to sign off your commit by using the option to “Commit (Signed Off)” in the “…” menu. Alternatively, you can directly amend the commit from the same menu. The SCM view always shows the HEAD commit at the bottom. Once you have created a commit, you can amend it to the previous one by pressing the “Amend button” and unamend respectively.

History / Blame

The “History View” is the second Git related view and provides an overview of all commits in the repository. You can expand a list of modified files for every commit and open a detailed view with all commit details. As in the SCM view, a double click on a file in this view opens a compare -view highlighting the changes. You can also open a history view filtered to a specific file by right clicking the file on it in the explorer and selecting “Git History”. To see the changes on a specific file “inline” you can toggle the “Blame annotations” in any file editor (via right click or ALT+B). This will show the last commit on every line, which contained changes on it.

Branching / Merging / Resolve Conflicts

To create a new branch or checkout an existing one, use the Command “Git: Checkout”. This will open another popup, in which you can select an existing branch by its name. If you want to create a new branch,  press enter without entering something and enter a name for the new branch in the second popup afterwards.

Merging can be triggered similarly via the command “Git: Merge” which allows you to select the branch to be merged into the current one.

…and more

This article is focussed on Git commands, which have some interesting UI interaction, rather than a full tutorial on Git in the Eclipse Theia IDE. You might miss some commands in this article, such as Git pull, push, fetch or stash. Most of these are available as commands for quick access and/or in the “…” menu in the SCM view. We recommend getting used to the typed commands, as this usually works quicker and you can keep your fingers on the keyboard.

Also keep in mind that you have full access to any Git command via the terminal in Theia, which also allows you to employ any additional tool of your choice, e.g. for merging.

In general, the Git workflow in Eclipse Theia is obviously very similar to VS Code and other modern tools. It focusses a lot on typed commands rather than using the mouse, -but adds visual support where it improves efficiency, i.e. when comparing, staging or browsing history.

Finally, as the Theia IDE is an extensible platform, you can adapt the Theia Git support to your needs. This can be done by adding existing plugins, even your favorite VS Code extensions or by creating your own extensions to Theia. This also allows to tailor the Git workflow to your specific use case, e.g. to simplify the workflow for non-software-engineers or adding a domain-specific merging view.

If you are interested in customizing the Git support or any other feature of Theia, please have a look at our consulting and support offerings for Eclipse Theia, for web-based tools or tools in general and please get in contact with us!

Finally, if you are interested in future parts of this series, e.g. how to extend Eclipse Theia and how to customize it, please follow us on Twitter, we will publish the next parts of this article series soon.