Codakey
Play
← Back to jesseduffield/lazygit

How to Deploy & Use jesseduffield/lazygit

# Lazygit Deployment & Usage Guide

## 1. Prerequisites

### Required
- **Git** (1.8.0+): Core functionality depends on Git commands
- **Terminal**: Any modern terminal with color support (iTerm2, Alacritty, Windows Terminal, etc.)

### For Building from Source
- **Go**: Version 1.22 or later (check `go.mod` for exact version requirements)
- **Make**: For using build scripts (optional but recommended)

### For Development
- **golangci-lint**: For code linting
- **Docker**: For integration testing (optional)

## 2. Installation

### Method 1: Binary Release (Recommended)
Download pre-built binaries from [GitHub Releases](https://github.com/jesseduffield/lazygit/releases):

```bash
# Linux/macOS (amd64)
curl -Lo lazygit.tar.gz "https://github.com/jesseduffield/lazygit/releases/latest/download/lazygit_$(uname -s)_$(uname -m).tar.gz"
tar xf lazygit.tar.gz lazygit
sudo install lazygit /usr/local/bin

# Verify installation
lazygit --version

Method 2: Homebrew

# macOS/Linux
brew install lazygit

# Upgrade
brew upgrade lazygit

Method 3: Go Install

go install github.com/jesseduffield/lazygit@latest

Ensure $GOPATH/bin or $GOBIN is in your $PATH.

Method 4: Build from Source

# Clone repository
git clone https://github.com/jesseduffield/lazygit.git
cd lazygit

# Build binary
go build -o lazygit

# Install to $GOPATH/bin or local directory
go install
# OR
mv lazygit /usr/local/bin/

Method 5: Package Managers

# Windows (Scoop)
scoop install lazygit

# Windows (Chocolatey)
choco install lazygit

# Arch Linux
sudo pacman -S lazygit

# Debian/Ubuntu (via PPA)
sudo add-apt-repository ppa:lazygit-team/release
sudo apt-get update
sudo apt-get install lazygit

# Fedora
sudo dnf install lazygit

3. Configuration

Configuration Directory

Lazygit follows XDG Base Directory specifications:

  • Linux/macOS: ~/.config/lazygit/
  • macOS (alternative): ~/Library/Application Support/lazygit/
  • Windows: %APPDATA%\lazygit\

Main Configuration File

Create config.yml in the config directory:

mkdir -p ~/.config/lazygit
touch ~/.config/lazygit/config.yml

Key configuration options:

gui:
  # Theme settings
  theme:
    activeBorderColor:
      - green
      - bold
    inactiveBorderColor:
      - white
  # Language (supports en, pl, etc.)
  language: "en"

git:
  # Paging settings
  paging:
    colorArg: always
    pager: delta  # optional: use delta for diffs
  
  # Commit preferences
  commit:
    signOff: false
  
  # Merge tool
  merging:
    manualCommit: false
    args: ""

# Custom commands
customCommands:
  - key: "C"
    command: "git commit -m '{{ .Form.Message }}'"
    description: "Commit with message"
    context: "files"
    prompts:
      - type: "input"
        title: "Commit message"
        initialValue: ""

Environment Variables

  • LG_CONFIG_FILE: Override default config file location 
    export LG_CONFIG_FILE=/path/to/config.yml
  • XDG_CONFIG_HOME: Change base config directory
  • GIT_CONFIG_GLOBAL: Specify global git config (lazygit respects this)

State Files

Lazygit maintains state in:

  • state.yml: UI state (window sizes, recent repos)
  • lazygit.log: Debug logs (when logging enabled)

Enable debug logging:

lazygit --debug
# Logs to ~/.config/lazygit/development.log

4. Build & Run

Development Build

# Clone and enter directory
git clone https://github.com/jesseduffield/lazygit.git
cd lazygit

# Install dependencies (vendored, but ensure modules available)
go mod download

# Run without building binary
go run main.go

# Build with version info (requires ldflags)
go build -ldflags="-X main.version=$(git describe --tags)" -o lazygit

Production Build

# Optimized build
go build -ldflags="-s -w -X main.version=$(git describe --tags)" -o lazygit

# Verify
./lazygit --version

Running Tests

# Unit tests
go test ./...

# Integration tests (requires Docker)
go test ./pkg/integration/clients -run Integration

# Specific integration test
go run main.go --local

# Linting
golangci-lint run

Cross-Compilation

# Linux
GOOS=linux GOARCH=amd64 go build -o lazygit-linux-amd64

# macOS
GOOS=darwin GOARCH=amd64 go build -o lazygit-darwin-amd64
GOOS=darwin GOARCH=arm64 go build -o lazygit-darwin-arm64

# Windows
GOOS=windows GOARCH=amd64 go build -o lazygit-windows-amd64.exe

5. Deployment

System-Wide Installation

# Linux/macOS
sudo cp lazygit /usr/local/bin/
sudo chmod +x /usr/local/bin/lazygit

# Or use install command
sudo install -Dm755 lazygit /usr/local/bin/lazygit

CI/CD Pipeline Integration

Add to GitHub Actions:

- name: Install Lazygit
  run: |
    curl -Lo lazygit.tar.gz "https://github.com/jesseduffield/lazygit/releases/latest/download/lazygit_Linux_x86_64.tar.gz"
    tar xf lazygit.tar.gz lazygit
    sudo install lazygit /usr/local/bin

Container Deployment

Dockerfile example:

FROM alpine:latest
RUN apk add --no-cache git curl
RUN curl -Lo lazygit.tar.gz "https://github.com/jesseduffield/lazygit/releases/latest/download/lazygit_Linux_x86_64.tar.gz" && \
    tar xf lazygit.tar.gz lazygit && \
    mv lazygit /usr/local/bin/ && \
    rm lazygit.tar.gz
ENTRYPOINT ["lazygit"]

Multi-User Setup

For shared servers, install to /opt:

sudo mkdir -p /opt/lazygit
sudo cp lazygit /opt/lazygit/
sudo ln -s /opt/lazygit/lazygit /usr/local/bin/lazygit

6. Troubleshooting

Build Issues

Error: "go: module not found"

  • Ensure Go 1.22+ is installed: go version
  • Clear module cache: go clean -modcache && go mod download

Error: "undefined: unsafe.Slice" or similar

  • Update Go to latest version (1.22+ required)

Runtime Issues

Garbled UI/Characters

  • Ensure terminal supports UTF-8
  • Try different terminal emulator
  • Set locale: export LC_ALL=en_US.UTF-8

Permission Denied on Config

# Fix permissions
chmod 755 ~/.config/lazygit
chmod 644 ~/.config/lazygit/config.yml

SSH Key Issues Lazygit uses vendored golang.org/x/crypto/ssh (shown in source). Ensure:

  • SSH keys are in standard locations (~/.ssh/id_rsa, ~/.ssh/id_ed25519)
  • Keys have proper permissions (600 for private keys)
  • Use SSH agent: eval $(ssh-agent -s) && ssh-add

Git Hooks Not Running Lazygit executes git commands directly. If hooks fail:

  • Check hook permissions: chmod +x .git/hooks/pre-commit
  • Verify hook syntax outside lazygit: .git/hooks/pre-commit

Performance Issues

Large Repositories Add to config.yml:

git:
  disableStat: true
  disableCommitGraph: true
  log:
    showGraph: false

Slow Startup

  • Disable auto-fetch: git.autoFetch: false
  • Clear lazygit logs: rm ~/.config/lazygit/development.log

Debug Mode

Enable verbose logging:

lazygit --debug
# Check logs at: ~/.config/lazygit/development.log

Common Key Conflicts

If terminal shortcuts override lazygit:

  • iTerm2: Disable "Option Key Sends Escape" if needed
  • tmux: Add set -g escape-time 10 to .tmux.conf
← Project overviewView alternatives to jesseduffield/lazygit →