GitHub - markrai/gitpow: an open-source, cross-platform git client

9 min read Original article ↗
image-Photoroom image image

Why?

This is a passion project of mine where I wanted a cross-platform git client, which would tackle some of the pain-points of existing solutions. Namely, conditional strategies to handle larger repositories (i.e. Kubernetes, Linux kernel, etc.) More importantly, I wanted to implement certain ergonomics which I didn't find in other clients, such as: showing image previews to visualize what changed (if an image was replaced, for example), grouping commits by month/year, giving the user more customization over how they wished to see dates (human-readable, versus timestamps), or how many "commits ago" a file was introduced. As a fun challenge, I wanted to provide the user the option to visualize the repo as a vertical, or horizontal graph, which could be navigated (and zoomed in/out of) on a touch-screen. This is a work in progress, and I welcome any suggestions, or better yet - contributions to the project! 😊

Prerequisites

All Platforms

  1. Rust (latest stable version)

    • Install from rustup.rs
    • Verify: rustc --version

  2. Node.js (v18 or later)

  3. wasm-pack

    • Install: cargo install wasm-pack
    • Verify: wasm-pack --version

  4. Tauri CLI

    • Install: cargo install tauri-cli
    • Verify: cargo tauri --version

Windows-Specific

  • Microsoft Visual C++ Build Tools or Visual Studio with C++ support
    • Required for building native dependencies
    • Download from Microsoft

Linux-Specific

Note: These are system-level dependencies required for Tauri applications on Linux. They cannot be bundled with the application and must be installed separately. This is standard practice for Linux GUI applications.

Install system dependencies:

Ubuntu/Debian:

sudo apt update
sudo apt install -y \
    libwebkit2gtk-4.1-dev \
    build-essential \
    curl \
    wget \
    file \
    libssl-dev \
    libgtk-3-dev \
    libayatana-appindicator3-dev \
    librsvg2-dev \
    libsoup-3.0-dev \
    libjavascriptcoregtk-4.1-dev \
    xdg-utils \
    pkg-config

Quick install script:

# The test script can automatically install missing dependencies
./test-linux-build.sh
# When prompted, answer 'Y' to install dependencies

Fedora:

sudo dnf install webkit2gtk4.1-devel.x86_64 \
    openssl-devel \
    curl \
    wget \
    file \
    libappindicator-gtk3 \
    librsvg2-devel

Arch Linux:

sudo pacman -S webkit2gtk \
    base-devel \
    curl \
    wget \
    openssl \
    libappindicator \
    librsvg

macOS-Specific

  1. Xcode Command Line Tools

  2. Homebrew (recommended)

    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Building Executables

Step 1: Install Dependencies

# Install Node.js dependencies
npm install

Step 2: Build WebAssembly Module

The graph visualization requires a WebAssembly module that must be built first:

Windows:

cd graph-wasm
wasm-pack build --target web
cd ..

Linux/macOS:

cd graph-wasm
wasm-pack build --target web
cd ..

Copy WASM files to static directory:

Windows:

if not exist "static\graph-wasm\pkg" mkdir "static\graph-wasm\pkg"
xcopy /Y /I "graph-wasm\pkg\*" "static\graph-wasm\pkg\"

Linux/macOS:

mkdir -p static/graph-wasm/pkg
cp -r graph-wasm/pkg/* static/graph-wasm/pkg/

Step 3: Build Executables

Windows

Development Build:

Release Build:

The executable will be located at:

src-tauri/target/release/gitpow.exe

Installer: The installer will be created at:

src-tauri/target/release/bundle/msi/gitpow_0.1.0_x64_en-US.msi

Linux

Quick Test (Recommended):

# Use the automated test script
chmod +x test-linux-build.sh
./test-linux-build.sh

Development Build:

Release Build:

The executable will be located at:

src-tauri/target/release/gitpow-tauri

(or target/release/gitpow-tauri if building from workspace root)

Note: The executable name is gitpow-tauri (matching the Cargo package name), not gitpow.

See LINUX-TEST-GUIDE.md for detailed Linux build instructions and troubleshooting.

AppImage:

src-tauri/target/release/bundle/appimage/gitpow_0.1.0_amd64.AppImage

Debian Package:

src-tauri/target/release/bundle/deb/gitpow_0.1.0_amd64.deb

macOS

Development Build:

Release Build:

The application bundle will be located at:

src-tauri/target/release/bundle/macos/GitPow.app

DMG:

src-tauri/target/release/bundle/dmg/gitpow_0.1.0_x64.dmg

Note: On macOS, you may need to sign the application for distribution. See Tauri's macOS Code Signing documentation.

Building for Specific Targets

Cross-Compilation

Building Windows executable from Linux/macOS

Install the Windows target:

rustup target add x86_64-pc-windows-gnu

Install MinGW-w64 (Linux):

# Ubuntu/Debian
sudo apt install gcc-mingw-w64-x86-64

# macOS
brew install mingw-w64

Build:

cargo tauri build --target x86_64-pc-windows-gnu

Building Linux executable from Windows/macOS

Install the Linux target:

rustup target add x86_64-unknown-linux-gnu

Use Docker or a Linux VM for building. See the Docker Build section below.

Building macOS executable from Linux/Windows

macOS executables must be built on macOS due to code signing requirements. You can:

  1. Build on a Mac:

  2. Use GitHub Actions with macOS runners (see .github/workflows/release.yml)

  3. Use a macOS CI/CD service (e.g., GitHub Actions, CircleCI with macOS support)

Docker cannot build macOS executables as macOS Docker images are not available for standard Docker setups.

Docker Build

For building in Docker containers (useful for isolated builds or cross-platform development), you can use the provided Docker setup.

GitPow is a fully cross-platform application that runs on Linux, Windows, and macOS. Docker is provided as a convenient way to build executables from any host OS.

Docker build support:

  • ✅ Linux (native) - can be built in Docker
  • ✅ Windows (cross-compiled using MinGW-w64) - can be built in Docker
  • ℹī¸ macOS - requires macOS host (see macOS Build section)

Note: macOS builds cannot be done in Docker due to macOS licensing restrictions. macOS is fully supported as a platform - you just need to build on a Mac. See the macOS Build section for instructions.

Prerequisites

  • Docker and Docker Compose installed
  • Git repository cloned

Building with Docker Compose

Building for Linux

The easiest way to build for Linux using Docker:

# Build the Docker image (first time only, or when dependencies change)
docker-compose build builder-linux

# Run the build (this will automatically build the application)
docker-compose run --rm builder-linux

Building for Windows (Cross-compilation)

You can cross-compile Windows executables from Linux using Docker:

# Build the Windows Docker image
docker-compose build builder-windows

# Run the Windows build
docker-compose run --rm builder-windows

The Windows executable will be at build-output/windows/gitpow-tauri.exe.

Building for All Platforms

To build both Linux and Windows:

# Build all images
docker-compose build

# Build Linux
docker-compose run --rm builder-linux

# Build Windows
docker-compose run --rm builder-windows

Or use the test script (Windows):

test-win&linux_builds.bat

Note: macOS is fully supported as a platform. Docker simply cannot build macOS executables due to macOS licensing restrictions, so macOS builds must be done on a Mac. See macOS Build section below.

macOS Build

macOS builds require a macOS system. To test the macOS build:

# On macOS, run the test script
chmod +x test-macos-build.sh
./test-macos-build.sh

Or build manually:

# Build WASM
cd graph-wasm && wasm-pack build --target web && cd ..
mkdir -p static/graph-wasm/pkg
cp -r graph-wasm/pkg/* static/graph-wasm/pkg/

# Build Tauri
cargo tauri build

The application bundle will be at:

  • src-tauri/target/release/bundle/macos/GitPow.app
  • DMG installer: src-tauri/target/release/bundle/dmg/gitpow_0.1.2_x64.dmg

The built executable will be available in:

  • Inside container: /gitpow/target/release/gitpow-tauri (when building from workspace root)
  • On host (if build-output directory exists): ./build-output/gitpow-tauri

Note: When building from the workspace root with Docker, the executable is at target/release/gitpow-tauri (not src-tauri/target/release/gitpow-tauri). This is because Cargo uses the workspace target directory when building from the root.

The docker-compose setup automatically:

  1. Mounts your project directory into the container
  2. Caches Cargo and Rustup data for faster subsequent builds
  3. Builds the WebAssembly module
  4. Builds the Tauri application
  5. Copies the executable to ./build-output/ if the directory exists

Note:

  • The first build may take 30-60 minutes. Subsequent builds are much faster due to caching.
  • The executable name is gitpow-tauri (matching the Cargo package name), not gitpow.
  • The built executable is a Linux binary (ELF format) and will not run natively on Windows. To test it:
    • Use WSL (Windows Subsystem for Linux): wsl ./build-output/gitpow-tauri
    • Transfer it to a Linux machine
    • Run it in the Docker container: docker-compose run --rm builder /gitpow/target/release/gitpow-tauri

Building with Docker directly

Alternatively, you can use the Dockerfile directly:

# Build the image
docker build -t gitpow-builder .

# Run the build (mount your source code)
docker run --rm \
  -v "$(pwd):/gitpow" \
  -v cargo-cache:/root/.cargo \
  -v rustup-cache:/root/.rustup \
  gitpow-builder \
  /bin/bash -c "cd /gitpow && rustup target add wasm32-unknown-unknown && cd graph-wasm && wasm-pack build --target web && cd .. && mkdir -p static/graph-wasm/pkg && cp -r graph-wasm/pkg/* static/graph-wasm/pkg/ && cargo tauri build"

Docker Image Details

The Docker setup uses jlesage/baseimage-gui:debian-12-v4 as the base image and includes:

  • All required system dependencies (including libsoup-3.0-dev, libjavascriptcoregtk-4.1-dev, xdg-utils)
  • Node.js (v24) via nvm
  • Rust toolchain via rustup
  • wasm-pack and tauri-cli

The build process:

  1. Clones the repository (or uses the current directory if mounted)
  2. Builds the WebAssembly module
  3. Copies WASM files to the static directory
  4. Builds the Tauri application

Note: The first build may take 30-60 minutes as it compiles all Rust dependencies. Subsequent builds are much faster due to Docker layer caching.

Development

Running in Development Mode

Windows:

Linux/macOS:

# Build WASM first
cd graph-wasm && wasm-pack build --target web && cd ..
mkdir -p static/graph-wasm/pkg
cp -r graph-wasm/pkg/* static/graph-wasm/pkg/

# Run Tauri dev
cargo tauri dev

Environment Variables

  • RUST_LOG: Controls Rust logging level (default: debug in dev mode)
    • Options: error, warn, info, debug, trace
    • Example: RUST_LOG=info cargo tauri dev

Build Output Locations

All build outputs are located in src-tauri/target/:

  • Debug builds: src-tauri/target/debug/
  • Release builds: src-tauri/target/release/
  • Bundles: src-tauri/target/release/bundle/

Troubleshooting

WebAssembly Build Issues

If wasm-pack build fails:

  1. Ensure wasm-pack is installed: cargo install wasm-pack
  2. Check Rust version: rustc --version (should be 1.70+)
  3. Install the wasm32 target: rustup target add wasm32-unknown-unknown

Tauri Build Issues

Windows:

  • Ensure Visual C++ Build Tools are installed
  • Check that cargo and rustc are in your PATH

Linux:

  • Verify all system dependencies are installed (see Prerequisites)
  • If GTK errors occur, install: sudo apt install libgtk-3-dev

macOS:

  • Ensure Xcode Command Line Tools are installed
  • If code signing errors occur, you may need to configure signing in tauri.conf.json

Missing Libraries.js

The static/libraries.js file is auto-generated during build. If it's missing:

  1. The build script (src-tauri/build.rs) should generate it automatically
  2. If it doesn't, ensure Cargo.toml and package.json are readable
  3. The file will be created in static/libraries.js during the build process

Build Time Issues

  • First build may take 10-30 minutes (compiling Rust dependencies)
  • Subsequent builds are much faster (incremental compilation)
  • Use cargo tauri build --debug for faster debug builds

Project Structure

gitpow-rust/
├── src/                    # Rust library code
├── src-tauri/              # Tauri application
│   ├── src/               # Tauri commands
│   ├── icons/             # Application icons
│   ├── build.rs           # Build script (generates libraries.js)
│   └── tauri.conf.json    # Tauri configuration
├── static/                # Frontend files
│   ├── js/                # JavaScript modules
│   ├── graph.js           # Graph visualization
│   └── index.html         # Main HTML file
├── graph-wasm/            # WebAssembly module
│   └── src/              # Rust WASM source
└── scripts/              # Build scripts

Features

Separation by month/year:

{96BCC32B-59F5-4F7E-B183-E984E54E4F34}

vertical graph view:

image

Image Diff Preview:

{B3A8E29F-60C6-4C9C-971A-952394CD09FB}