Debugging

If you are having technical issues with the GitButler client, here are a few things you can do to help us help you. Or help yourself.

If you get stuck or need help with anything, hit us up over on Discord, here's GitButler Discord Server Link.

The first things to try is checking out the frontend related logs in the console by opening the developer tools in GitButler via the "View" -> "Developer Tools" menu option. Next, if you launch GitButler from the command line, you can view the backend logs directly in your terminal.

Logs

Often the most helpful thing is to look at the logs. GitButler is a Tauri app, so the logs are in your OS's app log directory. This should be:

~/Library/Logs/com.gitbutler.app/

In this directory, there should be rolling daily logs:

❯ cd ~/Library/Logs/com.gitbutler.app
 
❯ tree -L 1
 
├── GitButler.log
├── GitButler.log.2023-09-02
├── GitButler.log.2023-09-03
├── GitButler.log.2023-09-04
├── GitButler.log.2023-09-05
├── GitButler.log.2023-09-06
├── GitButler.log.2023-09-07
├── GitButler.log.2023-09-08
├── GitButler.log.2023-10-10
├── GitButler.log.2024-01-30
└── tokio-console
 
❯ tail GitButler.log.2024-01-30
2024-01-30T13:02:56.319843Z  INFO get_public_key: gitbutler-app/src/keys/commands.rs:20: new
2024-01-30T13:02:56.320000Z  INFO git_get_global_config: gitbutler-app/src/commands.rs:116: new key="gitbutler.utmostDiscretion"
2024-01-30T13:02:56.320117Z  INFO git_get_global_config: gitbutler-app/src/commands.rs:116: new key="gitbutler.signCommits"
2024-01-30T13:02:56.320194Z  INFO get_public_key: gitbutler-app/src/keys/commands.rs:20: close time.busy=317µs time.idle=47.0µs
2024-01-30T13:02:56.320224Z  INFO git_get_global_config: gitbutler-app/src/commands.rs:116: close time.busy=204µs time.idle=25.3µs key="gitbutler.utmostDiscretion"
2024-01-30T13:02:56.320276Z  INFO git_get_global_config: gitbutler-app/src/commands.rs:116: close time.busy=133µs time.idle=35.8µs key="gitbutler.signCommits"
2024-01-30T13:02:56.343467Z  INFO menu_item_set_enabled: gitbutler-app/src/menu.rs:11: new menu_item_id="project/settings" enabled=false
2024-01-30T13:02:56.343524Z  INFO menu_item_set_enabled: gitbutler-app/src/menu.rs:11: close time.busy=35.7µs time.idle=28.8µs menu_item_id="project/settings" enabled=false

Data Files

GitButler also keeps its own data about each of your projects. The virtual branch metadata, your user config stuff, a log of changes in each file, etc. If you want to inspect what GitButler is doing or debug or reset everything, you can go to our data directory.

~/Library/Application Support/com.gitbutler.app/

In this folder there are a bunch of interesting things.

❯ cd ~/Library/Application\ Support/com.gitbutler.app
 
❯ tree
.
├── keys
│   ├── ed25519
│   └── ed25519.pub
├── projects.json
└── settings.json
 
4 directories, 4 files

The projects.json file will have a list of your projects metadata:

❯ cat projects.json
[
  {
    "id": "71218b1b-ee2e-4e0f-8393-54f467cd665b",
    "title": "gitbutler-blog",
    "description": null,
    "path": "/Users/scottchacon/projects/gitbutler-blog",
    "preferred_key": "generated",
    "ok_with_force_push": true,
    "api": null,
    "gitbutler_data_last_fetch": null,
    "gitbutler_code_push_state": null,
    "project_data_last_fetch": {
      "fetched": {
        "timestamp": {
          "secs_since_epoch": 1706619724,
          "nanos_since_epoch": 202467000
        }
      }
    }
  }
]

The settings.json are some top level preferences you've set.

❯ cat settings.json
{
  "appAnalyticsConfirmed": true,
  "appNonAnonMetricsEnabled": true
}

Finally, the keys directory holds the SSH key that we generate for you in case you don't want to go through creating your own. It's only used if you want to use it to sign commits or use it for authentication.

Per-project repository data

Most repository-specific GitButler state lives next to the repository itself, inside the .git directory. By default, GitButler stores that data in .git/gitbutler for release builds, nightly builds and developer builds.

You can override that location with a Git config change, here for the stable build:

❯ git config --local gitbutler.storagePath gitbutler-alt

You can also set it globally if you want all repositories opened by GitButler on that machine to use the same base configuration:

Setting it to a shared directory is useful if the project locations themselves are on a filesystem that doesn't support Sqlite very well, like a network drive.

❯ git config --global gitbutler.storagePath /path/to/gitbutler-projects

Setting it to a relative path would force a channel, like Nightly, to reuse the data of stable builds.

❯ git config --global gitbutler.nightly.storagePath gitbutler

The Git config key depends on the app channel:

• Release builds use gitbutler.storagePath
• Nightly builds use gitbutler.nightly.storagePath
• Developer builds use gitbutler.dev.storagePath

There are a couple of constraints on the configured path:

• Relative paths are resolved relative to the repository's .git directory
• If the resolved path stays inside .git, it must be under a top-level directory whose name starts with gitbutler, case-insensitive
• You cannot point it at .git itself
• If the resolved path ends up outside .git, GitButler appends a project-path specific identifier so multiple repositories can share the same base directory safely

For example, these are valid:

❯ git config --local gitbutler.storagePath gitbutler-alt
❯ git config --local gitbutler.storagePath ../../gitbutler-projects

If you use a path outside .git, GitButler treats it as a base directory. For example, ../../gitbutler-projects becomes something like ../../gitbutler-projects/<project-handle> after resolution.

Linux

glibc Errors

The Linux installation is currently being built in a GitHub Action with Ubuntu 24.04. This means support is limited to those installations using the same or newer version of glibc. Unfortunately we cannot build using earlier versions of Ubuntu due to another incompatibility with libwebkit2gtk-4.1 and Tauri at the moment.

If you're using an older distribution, you may be interested in trying our Flatpak package available on Flathub.

Failed to create EGL image from DMABuf

If you start GitButler from the command line and see a bunch of these or similar EGL / DMABuf related messages printed to the console and are only getting a white screen to render, you can try launching GitButler with the following environment variables:

• WEBKIT_DISABLE_DMABUF_RENDERER=1
• WEBKIT_DISABLE_COMPOSITING_MODE=1

This issue most likely stems from an incompatibility between your version of OpenGL (mesa) and libwebkit2gtk-4.1.