ejiek/git-plumber repository overview

⁠git-plumber

⁠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. 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 “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

⁠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

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

⁠Analyze specific repository

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