zed-git-view

zgv — A Modern TUI Git Client

A keyboard-first, terminal-based Git client built with Go and the Charm ecosystem. Designed to run inside Zed's integrated terminal (or any terminal emulator).

Features

Installation

Homebrew (macOS / Linux)

brew install Akashdeep-Patra/tap/zgv

Go install

# Requires Go 1.22+
go install github.com/Akashdeep-Patra/zed-git-view/cmd@latest

Download binary

Pre-built binaries for Linux, macOS, Windows (amd64 + arm64) are available on the Releases page.

Each release includes SHA-256 checksums and SBOM for verification:

# Verify checksum after download
sha256sum -c checksums.txt --ignore-missing

Linux packages

.deb, .rpm, and .apk packages are attached to each GitHub Release.

# Debian / Ubuntu
sudo dpkg -i zgv_*.deb

# Fedora / RHEL
sudo rpm -i zgv_*.rpm

# Alpine
sudo apk add --allow-untrusted zgv_*.apk

Build from source

git clone https://github.com/Akashdeep-Patra/zed-git-view.git
cd zed-git-view
task build          # or: go build -o bin/zgv ./cmd/
./bin/zgv

Usage

# Run in the current directory
zgv

# Run in a specific repo
zgv --path /path/to/repo

# Print version
zgv version
zgv version --json

# Shell completions
zgv completion bash   # also: zsh, fish, powershell

Keyboard Shortcuts

Global

Status View

Diff View

Branch View

Configuration

Configuration file: ~/.config/zgv/config.yaml

theme: dark
max_log_entries: 200
confirm_destructive: true
diff_context_lines: 3
side_by_side_diff: false

Environment variables (prefixed with ZGV_):

export ZGV_MAX_LOG_ENTRIES=500

Versioning

This project follows Semantic Versioning.

• Version is injected at build time via Go ldflags.
• zgv version prints version, commit hash, build date, Go version, and OS/arch.
• zgv version --json outputs machine-readable version info.
• Tags follow the format v{major}.{minor}.{patch} (e.g., v0.1.0).

Creating a release

# Update CHANGELOG.md, commit, then tag:
git tag -a v0.2.0 -m "Release v0.2.0"
git push origin v0.2.0

# Or use the Taskfile shortcut:
task tag -- v0.2.0

Pushing a v* tag triggers the release workflow which:

1. Runs all CI checks.
2. Builds binaries for 6 platform/arch combos.
3. Creates .deb, .rpm, .apk packages.
4. Generates SHA-256 checksums.
5. Signs artifacts with cosign (keyless, Sigstore).
6. Generates an SBOM (Software Bill of Materials).
7. Publishes a GitHub Release with all artifacts.
8. Updates the Homebrew formula.

Tech Stack

• Go — fast, single binary, no runtime deps
• Bubbletea — Elm Architecture TUI framework
• Lipgloss — CSS-like terminal styling
• Bubbles — pre-built TUI components
• Cobra — CLI framework with completions
• Viper — configuration management
• Git CLI — shells out to git for maximum compatibility

CI/CD

GitHub Actions handles everything automatically. PRs cannot merge unless all CI checks pass (configure branch protection rules for enforcement).

Project Structure

cmd/main.go              Entry point (Cobra CLI, version, completions)
internal/
  app/                   App model, keybindings, orchestration
  common/                Shared types (TabID, messages, View interface)
  config/                Viper-based configuration
  git/                   Git service interface + CLI implementation
  ui/
    theme.go             Catppuccin-inspired dark theme
    layout.go            Layout helpers
    components/          Shared components (tabs, statusbar, help, dialog, side-by-side diff)
    views/               One file per tab (status, log, diff, branches, stash, remotes, rebase, conflicts, worktrees, bisect)
.github/workflows/
  ci.yml                 CI: lint, test, vet, build on every push/PR
  release.yml            Release: goreleaser on tag push
.goreleaser.yml          Multi-platform build + package + publish config
Taskfile.yml             Development task runner (build, test, lint, tag, etc.)
.golangci.yml            Linter configuration
CHANGELOG.md             Keep a Changelog format
CONTRIBUTING.md          Contribution guidelines
LICENSE                  MIT

Development

# Install task runner
brew install go-task

# Common commands
task build          # Build binary (with version metadata)
task dev            # Run with go run
task test           # Run tests with race detector
task lint           # Run golangci-lint
task check          # fmt + vet + lint + test
task snapshot       # GoReleaser snapshot (local, no publish)
task release:dry    # Full release dry-run
task version        # Print current version from git tags
task tag -- v0.2.0  # Tag and push a release

Contributing

See CONTRIBUTING.md for setup, workflow, and coding standards.

License

MIT