Installing GitButler on Windows via WSL

GitButler-WSL.md

Installing GitButler on Windows via WSL - A Complete Guide

This guide will provide a complete walkthrough for getting GitButler setup and functioning on a windows environment using Windows Subsystem for Linux (WSL).

Please note that GitButler on windows via wsl is not well tested and not officially supported, though one of the top priorities of the GitButler team is to get a working windows build out asap. For now, however this is the easiest solution I have developed.

Prerequisites:

• You must be running Windows 10 version 2004 and higher (Build 19041 and higher) or Windows 11 for this guide to work correctly.
• I highly suggest using the windows terminal app for doing all the command line work if you are not using it already, though this is not required.

Known Issues

• Trying to work with a repo hosted on the windows filesystem using this method is laggy at best and may completely time out at worst. This method works best if you are using WSL as your dev environment rather than Windows as your dev environment.
• The Sign up or Log in button on the welcome page after first installing GitButler does not work.
• When you close a git butler window, the Ubuntu process is not killed. This will result in many instances of the git-butler process running at the same time if you have opened and closed the program multiple times. To solve this, you can run the pkill -x git-butler command to manually kill all currently running git-butler processes. You can follow the github issue here: gitbutlerapp/gitbutler#2667

WSL Installation

To start we must use the wsl command in windows to set up our linux environment in windows. If you already have a WSL instance up and running, you can skip ahead to the GitButler Install portion of this guide.

To start, you will need to open a powershell window as administrator and run the following command:

wsl --install

Once this has completed, you should restart your computer.

After your computer is restarted you can open the Ubuntu progam that is now listed in your start menu, or open a new Ubuntu terminal using the windows terminal program.

In the Ubuntu terminal you should now run:

$ sudo apt update && sudo apt -y upgrade

This will get your system fully up to date, and now we can move on to installing GitButler!

GitButler Install

Before we can install GitButler there are two programs that we need to make sure are installed first:

$ sudo apt install -y firefox wslu

This will install the firefox browser as well as some wsl utilities. These are necessary to be able to login to your GitButler account once you install gitbutler.

While those are installing, go to https://gitbutler.com and download either the Linux Deb or Linux AppImage version of GitButler.

AppImage vs Deb

There are a few pros/cons to each. If you use the deb you will need to manually update any time there is a new GitButler version by downloading the new deb and running the below install process for each new version. The AppImage on the other hand will prompt you when there are updates and can be quickly and easily updated, however there is more initial setup required to add a desktop shortcut on windows that will properly launch the AppImage version.

Deb Install Instructions

Once you have the Linux Deb version downloaded, open up windows file explorer, and in the document url bar near the top type in \\wsl.localhost\Ubuntu\home\ and then press enter. Then select the folder with your Ubuntu username. This is where we will want to place the .deb file we downloaded from the GitButler website so that we can access it inside our Ubuntu instance. Go ahead and do this now.

Lets go back to our Ubuntu instance and cd ~/ to make sure you are in your home directory. If you use the ls command you should be able to see the .deb file that you put there in the previous step. In my case the file is called git-butler_0.10.7_amd64.deb.

Now we are ready to start installing git butler. Run the following command (replacing the git-butler_0.10.7_amd64.deb file name with the name of the .deb file that you downloaded) to start the process:

$ sudo dpkg -i git-butler_0.10.7_amd64.deb

Once it is done running it will show that there were dependency errors. This is ok. To solve the dependency errors we need to run the following command:

$ sudo apt install -y -f

This will take a while as there are many dependency packages to install. Once the dependencies are installed, you can now open git butler for the first time using the following command.

$ git-butler

AppImage Install Instructions

Once you have the Linux AppImage version downloaded, open up windows file explorer, and in the document url bar near the top type in \\wsl.localhost\Ubuntu\home\ and then press enter. Then select the folder with your Ubuntu username. This is where we will want to place the .AppImage.tar.gz file we downloaded from the GitButler website so that we can access it inside our Ubuntu instance. Go ahead and do this now.

Lets go back to our Ubuntu instance and cd ~/ to make sure you are in your home directory. If you use the ls command you should be able to see the .AppImage.tar.gz file that you put there in the previous step. In my case the file is called git-butler_0.10.6_amd64.AppImage.tar.gz.

Next lets extract the .AppImage by running the following command (please replace the file name with the file you downloaded):

$ tar -xzf git-butler_0.10.6_amd64.AppImage.tar.gz

Before we can run the extracted AppImage we have to install a few extra packages that are required to make it run:

$ sudo apt install -y fuse libopengl0

Once those packages are installed you can simply run $ ./git-butler_0.10.6.AppImage to launch git butler directly, and the setup instructions below should work ok. However if you do not want to launch it from the command line every time, we need to do some more setup.

From here the easiest way to get the AppImage setup to act like a normally installed app would be to use AppImageLauncher. However, for the sake of this tutorial I am going to provide instructions to integrate the AppImage manually so as to avoid requiring the install of possibly untrusted software.

First I would suggest renaming the package to git-butler to make the rest of the commands simpler and easier to type out:

$ mv git-butler_0.10.6_amd64.AppImage git-butler

Next, lets symlink our app image to /usr/bin so that its in a location that ubuntu expects:

$ sudo ln -s ~/git-butler /usr/bin/

If you are storing the git-butler AppImage somewhere else, make sure that you adjust the symlink target path to match where you have it stored.

Next we will need to extract the git-butler.desktop file from the AppImage along with the icon files and move the .desktop file to /usr/share/applications, and move the icon files to /usr/share/icons so that windows knows to add it to the list of applications installed on your Ubuntu WSL instance, and uses the correct icon.

First lets unwrap the AppImage by running:

$ git-butler --appimage-extract

This will create a squashfs-root directory with the git-butler.desktop file and icon directory we will need inside. Lets start by copying over the icon files first before moving the desktop file so that windows picks up the icons correctly.

$ sudo cp -r squashfs-root/usr/share/icons /usr/share/

Next lets move the .desktop file to where it needs to go, and then remove the squashfs-root directory:

$ sudo cp squashfs-root/git-butler.desktop /usr/share/applications/
$ rm -rf squashfs-root/

And thats it! Git butler should now show up in the windows start menu app list under the Ubuntu folder. See the setup instructions below for more info on creating desktop or taskbar shortcuts.

Setting Up GitButler

Once you have gitbutler installed and running, you will need to accept (or not) the initial data collection agreements, before getting to the main welcome screen for a fresh install.

GitButler account sign in

The big "Log in or Sign up" button in the middle of the left pane is now working as of 0.10.13! So just click that button and wait a few moments for the firefox window to open. Once the firefox window is open, you can log in or create a new account.

Add new project repo

Clicking the large Add new project button on the welcome page will open a file browser where you can navigate to your project directory. If your project directory is in your Windows file system, you can navigate to /mnt/c/ to access your windows C: drive. If you have other drives in windows they should also be available in the /mnt/ directory in your linux instance.

Creating a Windows Desktop/Taskbar shortcut to quickly launch GitButler

Open the windows start menu and at the top under "Recently Added" should be the program GitButler (Ubuntu). You can drag this to the desktop or taskbar to create a shortcut. If it is not under the "Recently Added" section, you can scroll down to the Ubuntu folder and you should find the GitButler (Ubuntu) app inside. From there you should be able to create your desktop or taskbar shortcut.

Be warned that opening projects in a Windows filesystem using /mnt/c/ can be extremely slow. GitButler couldn't open one of my larger projects at all due to timing out while initially setting itself up with virtual branches. In contrast, cloning the project to the WSL filesystem let me open it instantly (though that doesn't help for me since I work in Visual Studio which fails to load some of the projects when opening from \\wsl.localhost\Ubuntu\home\).

Be warned that opening projects in a Windows filesystem using /mnt/c/ can be extremely slow. In contrast, cloning the project to the WSL filesystem let me open it instantly

This is good to know. I use WSL as my primary dev environment so I only briefly tested getting it to work using /mnt/c/. Sounds like this work around is really only useful if you use WSL as your dev environment.

Updated the instructions to provide full install instructions for both the .deb as well as the AppImage since the AppImage is the only version that supports automatic updates on new releases.

Thanks for the awesome instructions, but one thing to add for the AppImage instructions is to copy over the squashfs-root/usr/share/icons/ directory over from the squashfs-root directory to /usr/share/ directory before copying over the git-butler.desktop file so that Windows correctly picks up the icons.

Be warned that opening projects in a Windows filesystem using /mnt/c/ can be extremely slow. In contrast, cloning the project to the WSL filesystem let me open it instantly

This is good to know. I use WSL as my primary dev environment so I only briefly tested getting it to work using /mnt/c/. Sounds like this work around is really only useful if you use WSL as your dev environment.

Come to think of it, I wonder if any of the options listed in wsl docs like mounting a VHD would help, or maybe even the fancy new Dev Drives with ReFS, assuming they are or can be made mountable? I suspect most of the overhead comes from the 9p protocol though, but that might improve soon!

Here's also an official comment from 2020 about the topic: microsoft/WSL#4197

I also found some workarounds on Stack Overflow, apparently WSL1 performs better in this regard (but still not 100% and obviously has other drawbacks), and using NFS to share and mount manually is also faster. YMMV.

Edit: Also, Visual Studio can do C++ projects in WSL! But dotnet seems limited to running and debugging only :(

Thanks for the awesome instructions, but one thing to add for the AppImage instructions is to copy over the squashfs-root/usr/share/icons/ directory over from the squashfs-root directory to /usr/share/ directory before copying over the git-butler.desktop file so that Windows correctly picks up the icons.

Thanks for the info on this. I was originally going to add steps to do this but I was in a bit of a hurry and couldnt quickly figure out where the icon files needed to go so that they would be properly picked up by windows.

Is anyone else getting the error (git-butler:2327): Gtk-WARNING **: 08:08:33.057: cannot open display: :0 ?

I tried running sudo apt install -y -f, it didn't install anything new.

Can't launch the app.

UPDATE: Running sudo git-butler solves this and launches git-butler.

But I still can't launch it from the Windows Start Menu :(

Any suggestions?

UPDATE: Running sudo git-butler solves this and launches git-butler.

But I still can't launch it from the Windows Start Menu :(

Any suggestions?

yeah, you can edit shortcut to launch by sudo user.
Example: "C:\Program Files\WSL\wslg.exe" -d Ubuntu -- echo "$pass" | sudo -S git-butler

I think, the guide needs to be updated:

$ sudo dpkg -i /mnt/c/Users/koppor/Downloads/git-butler_0.10.27_amd64.deb
Selecting previously unselected package git-butler.
(Reading database ... 48594 files and directories currently installed.)
Preparing to unpack .../git-butler_0.10.27_amd64.deb ...
Unpacking git-butler (0.10.27) ...
dpkg: dependency problems prevent configuration of git-butler:
 git-butler depends on libwebkit2gtk-4.0-37; however:
  Package libwebkit2gtk-4.0-37 is not installed.

dpkg: error processing package git-butler (--install):
 dependency problems - leaving unconfigured

Maybe, switch to gdebi?

sudo gdebi git-butler_0.10.27_amd64.deb

if you hit this error while launching git-butler from command-line

error while loading shared libraries: libEGL.so.1: cannot open shared object file: No such file

just run this command

sudo apt install libegl1

If you encounter the following error when launching git-butler from command-line

git-butler: error while loading shared libraries: libharfbuzz.so.0: cannot open shared object file: No such file or directory

run the following command

sudo apt install libharfbuzz0b

@KroniK907, I appreciate your effort to write this guide. 💯 🥇

I really wanted to try out GitButler with my WSL dev environment and thanks to you I managed to do so. 🙇

I'm using version 0.11.7 and the login button does not work. GitButler initialized correctly, I have Firefox in Ubuntu installed alongside the other dependencies mentioned here. There are also no errors shown in the terminal during the AppImage execution, it just doesn't open the link. Where I do see errors is in the console within the Tauri app (View > Developer Tools): Failed to load resource: the server responded with a status of 401 (Unauthorized) https://app.gitbutler.com/api/login/user/5a872d7c214353e5a457db03359.json

EDIT:
using sudo git-butler fixes the link opening issue

sudo dpkg -i git-butler_0.10.7_amd64.deb
dpkg: error: cannot access archive 'git-butler_0.10.7_amd64.deb': No such file or directory

maybe the installer could be updated or provided with current dependencies. Or even as a snap. Seem to be endless missing dependency journey with wsl and ubuntu 24-04 (yes it's (too) recent )