How mlange-42/git-graph works
Project type and purpose
• This is an open-source, command-line Rust tool (a Cargo crate) called “git-graph.”
• Its purpose is to read a Git repository’s history, build an internal graph representation of commits and branches (following user-selectable branching models), and render that graph in the terminal (or to SVG).
File structure
• Top-level:
• Cargo.toml / Cargo.lock: Rust package metadata and dependency lockfile
• src/: Rust source code
• docs/: user manual and model specification
• .github/workflows/: CI for tests, releases
• Justfile: build/automation shortcuts
• src/ layout:
• main.rs: CLI entrypoint
• lib.rs: public crate interface
• config.rs + settings.rs: loading CLI flags, config files, default settings
• graph.rs: core graph-building logic (parsing Git history, modeling commits/branches)
• print/: rendering logic
• External dependencies in Cargo.toml (e.g., clap for argument parsing, serde/toml for config, git2 or shelling out to git).
README for additional insights
• Describes features: structured graphs, branching models, ASCII or Unicode output, custom formatting.
• Mentions custom branching models loaded from user’s AppData/.config folder (TOML files).
Components and their relationships
a. Main components:
1. CLI Parser (main.rs + lib.rs using clap or structopt)
2. Configuration Loader (config.rs + settings.rs)
3. Git Adapter (calls out to git log or uses git2)
4. Graph Builder (graph.rs)
5. Renderer/Printer (print/ module)
6. Output Sink (terminal stdout or SVG file)
7. User Model Store (TOML files in ~/.config/git-graph/models)
b. Data flow:
[User invokes git-graph]
↓ CLI Parser parses flags & subcommands
↓ Configuration Loader merges defaults + CLI + user model file
↓ Git Adapter reads repository history → hands commit list to
↓ Graph Builder constructs internal node/edge model
↓ Output Sink writes to stdout or to an .svg file
c. Architectural patterns/design principles:
• Separation of concerns: parsing, config, graph logic, presentation are in separate modules
• Plugin/extension point: custom branching models loaded at runtime
• Single responsibility: each print module handles exactly one style
d. Key technologies:
• Rust programming language
• Cargo for build & dependency management
• clap (or structopt) for CLI
• serde + toml for config/model deserialization
• git2 or shelling-out for Git data
• svg crate or manual XML templating in svg.rs
Elements
• “CLI Parser”
• “Config Loader”
• “Git Adapter”
• “Graph Builder”
• “Printer Modules”
• “Output Sink”
• “Model Store (TOML files)”
• External services:
• Git binary / Git library
• Terminal / File system
• Data flow from user → CLI Parser → … → Output Sink
• How Config Loader reads from Model Store
• Git Adapter ↔ Git binary
• External dependencies (green clouds)
• Labels:
Detailed capture of architectural elements
• Plugin directory as a separate file store.
• That Cargo.toml/Cargo.lock drive versioning but aren’t part of runtime.
[User CLI Invocation]
↓
+------------------+
| CLI Parser |
+------------------+
↓
+------------------+ ←── reads TOML ── [Model Store: ~/.config/git-graph/models]
| Config Loader |
+------------------+
↓
+------------------+ ↔── calls ── [Git binary or git2 library]
| Git Adapter |
+------------------+
↓
+------------------+
| Graph Builder |
+------------------+
↓
+-----------------------------+
| Printer Modules |
| ┌──────┐ ┌──────┐ ┌──────┐ |
| |ASCII | |Unicode| | SVG | |
| └──────┘ └──────┘ └──────┘ |
+-----------------------------+
↓
[Terminal stdout] or [output.svg]