Command Palette
Search for a command to run...

Installing pgit

Discussions

Install the pgit CLI with Go, a prebuilt binary, or a system package, then verify the one runtime requirement.

how-to · beginner · 10m
applies to pgit 4, docker, podman
by Oliver Seifert ·

Installing pgit

pgit ships as a single static binary. Installing it is quick; the one thing to get right is the runtime requirement, because the local database lives in a container.

Requirements

  • Docker or Podman. pgit runs PostgreSQL (with pg-xpatch) in a container for the local database. One of the two must be installed and working.
  • git, only if you plan to import an existing repository. Import shells out to git fast-export.
  • A pg-xpatch PostgreSQL server, only for remote push / pull / clone. The local container already includes pg-xpatch, so you do not need a separate server for local use.
Why a container instead of embedded PostgreSQL?

pg-xpatch is a compiled PostgreSQL extension. Bundling and cross-compiling it for every OS proved impractical, so pgit leans on a prebuilt image (ghcr.io/imgajeed76/pg-xpatch) instead. The trade-off buys reliable cross-platform behaviour for the cost of a container runtime.

Install the CLI

go install github.com/imgajeed76/pgit/v4/cmd/pgit@latest

The binary lands in your Go bin directory (usually ~/go/bin). Make sure that directory is on your PATH.

Download the archive for your platform from the releases page, unpack it, and put pgit somewhere on your PATH.

  • Linux: pgit_*_linux_amd64.tar.gz or pgit_*_linux_arm64.tar.gz
  • macOS: pgit_*_darwin_amd64.tar.gz or pgit_*_darwin_arm64.tar.gz
  • Windows: pgit_*_windows_amd64.zip

Grab the package matching your distro from the releases page, then:

# Debian / Ubuntusudo dpkg -i pgit_*_linux_amd64.deb# RHEL / Fedorasudo rpm -i pgit_*_linux_amd64.rpm# Alpinesudo apk add --allow-untrusted pgit_*_linux_amd64.apk

Packages install the binary to /usr/bin/pgit.

Confirm the binary runs:

pgit version

Pick a container runtime

pgit auto-detects the runtime. It prefers Docker and falls back to Podman. To force one, set PGIT_CONTAINER_RUNTIME:

export PGIT_CONTAINER_RUNTIME=podman   # or docker

Verify your setup

pgit doctor runs through everything pgit needs and tells you what, if anything, is missing.

First run

1

Check the runtime and overall health:

pgit doctor

It reports the container runtime and version, container status, and (inside a repo) the database connection and your commit identity.

2

Start the local database container:

pgit local start

The first start pulls the pg-xpatch image and brings PostgreSQL up on port 5433 (bound to localhost). A later import or commit would start it for you anyway, so this step is optional but reassuring.

3

You are ready. Head to the quickstart to import a repo.

Shell completions

pgit generates completions for bash, zsh, fish, and PowerShell. For example: pgit completion zsh > "${fpath[1]}/_pgit". Run pgit completion --help for the per-shell install line.

Next

Quickstart

Import a real repository and run your first analysis.

Managing the local container

Start, stop, update, and reset the shared database container.

Did this work on your setup?

Not rated yet

Sign in so your verification counts for more.