git-plumber

[!IMPORTANT] Pre-release software. Expect bugs and incomplete features.

🎥 Click above to watch git-plumber in action (asciinema demo)

What is git-plumber?

git-plumber is a CLI and TUI application for exploring the internals of git repositories in a safe, read-only way. Browse and understand the contents of the .git/ directory: refs, trees, blobs and more. Demystify compressed and binary “plumbing” beneath git’s familiar porcelain appearance.

Perfect for learning, live experimentation, or just satisfying your curiosity.

Use cases

• Learning with “Pro Git” 10. Git Internals): Fire up git-plumber in a test repository and see immediately how every command reshapes your repo’s internals.
• Understanding git storage: See for yourself how git stores differences between versions — the reason this app was created!

What git-plumber is not?

• Not a replacement for everyday git workflow
• Not a “porcelain” UI like gitui or lazygit
• Not an interface for running plumbing commands, but a worthy alternative to git cat-file or git verify-pack

Installation

Development version

Dev versions are built from the latest main commit. They are available:

• Nix Flake: nix run github:ejiektpobehuk/git-plumber
• Container images
  • ejiek/git-plumber:dev at Docker Hub
  • ghcr.io/ejiektpobehuk/git-plumber:dev
• Arch User Repository
• From source

Versioned releases

They are built from tags, are more rare and still not stable. However, they have better availability:

• crates.io/git-plumber
• Nix Flake: nix run github:ejiektpobehuk/git-plumber/${VERSION}
• Container images at
  • Docker Hub
  • GitHub Container Registry
• Release Binaries

More packaging details are available in issue #1

Building from source

Prerequisites:

• Rust and Cargo installed
• Minimum Supported Rust Version 1.88

git clone https://github.com/ejiektpobehuk/git-plumber.git
cd git-plumber
cargo install --path .

Roadmap & Contributions

This app is my git learning project. It's going to be more complete as my knowledge grows.

For planned features checkout issues at GitHub.

Major goals:

• Support for all native git files
• Internationalization (i18n)
• git-bug support
• jj support

PRs/issues welcome — no need to be a git guru! Beginners and documentation helpers are especially appreciated. If something is unclear, that’s a sign the app can get better: lease open an issue or start a discussion!

Read the project’s Guiding Principles and contribution tips in CONTRIBUTING.md.

Why the 'git-plumber' name?

In Git terms, “porcelain” is the friendly VCS user-facing interface, while “plumbing” is the low-level machinery underneath — the content‑addressed filesystem with packfiles, deltas and much more. It's described in more details in Pro Git, Chapter 10.1 Git Internals - Plumbing and Porcelain.

git-plumber helps you to explore the plumbing part.

License

MIT

Credits & Inspiration

• Pro Git, Chapter 10: Git Internals
• Git pack-format documentation

Not a git management tool. Not for your day-to-day workflow. This is for those who want to see git’s wiring and learn how it all fits together.

🕳️ Happy plumbing! 🔧