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.
- 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.
- 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 inbutton 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-butlerprocess running at the same time if you have opened and closed the program multiple times. To solve this, you can run thepkill -x git-butlercommand to manually kill all currently running git-butler processes. You can follow the github issue here: gitbutlerapp/gitbutler#2667
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 upgradeThis will get your system fully up to date, and now we can move on to installing GitButler!
Before we can install GitButler there are two programs that we need to make sure are installed first:
$ sudo apt install -y firefox wsluThis 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.
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.
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.debOnce 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 -fThis 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-butlerOnce 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.gzBefore 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 libopengl0Once 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-butlerNext, 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-extractThis 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.
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.
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.
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.
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.
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 filejust run this command
sudo apt install libegl1