ejiek/git-plumber

git-plumber

https://raw.githubusercontent.com/ejiektpobehuk/git-plumber/preview-assets/git-plumber.gif](https://asciinema.org/a/728563)

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

What is git-plumber?

https://github.com/ejiektpobehuk/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. Demystifying compressed and binary “plumbing” beneath git’s familiar porcelain appearance.

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

Use cases

• Learning with https://git-scm.com/book/en/v2/Git-Internals-Plumbing-and-Porcelain): 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 https://github.com/extrawurst/gitui or https://github.com/jesseduffield/lazygit
• Not an interface for running plumbing commands, but a worthy alternative to git cat-file or git verify-pack

Usage

git-plumber is available as a minimal Docker image optimized for size and security. Nothig but the binary. You have to pass a git repository as a volume.

• Size: <1MB
• Base: scratch (empty base image)
• Binary: Static musl build
• Platforms: Linux x86_64 and ARM64

Analyze current directory

bash
docker run --rm -v $(pwd):/workspace git-plumber:latest

Analyze specific repository

bash
docker run --rm -v /path/to/repo:/workspace git-plumber:latest

Available Tags

• git-plumber:latest - Latest versioned release
• git-plumber:v0.1.2 - Specific version
• git-plumber:dev - Built from the latest main commit
• ghcr.io/ejiektpobehuk/git-plumber:* - GitHub Container Registry mirror

Limitations

• No shell access: Built on scratch base for minimal size
• No additional tools: Contains only the git-plumber binary

Roadmap & Contributions

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

For planned features checkout https://github.com/ejiektpobehuk/git-plumber/issues.

Major goals:

• Support for all native git files
• Internationalization (i18n)
• https://github.com/git-bug/git-bug support
• https://github.com/jj-vcs/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 https://github.com/ejiektpobehuk/git-plumber/issues/new or start a discussion!

Read the project’s Guiding Principles and contribution tips in https://github.com/ejiektpobehuk/git-plumber/blob/main/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 https://git-scm.com/book/en/v2/Git-Internals-Plumbing-and-Porcelain.

git-plumber helps you to explore the plumbing part.

License

MIT

Credits & Inspiration

• Pro Git, https://git-scm.com/book/en/v2/Git-Internals-Plumbing-and-Porcelain
• https://git-scm.com/book/en/v2/Git-Internals-Plumbing-and-Porcelain

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! 🔧