# serie: git commit graph viewer that renders images in the terminal > serie is a MIT-licensed Rust TUI application that replaces git log --graph with a commit graph rendered as actual images using terminal image protocols. It requires a compatible terminal (iTerm2 or kitty) and does not support Sixel, Windows, or most multiplexers. **lusingander/serie** — A rich git commit graph in your terminal, like magic 📚 - Repository: https://github.com/lusingander/serie - Website: https://lusingander.github.io/serie/ - Stars: 2,162 · Forks: 66 - Language: Rust - License: MIT - Published: 2026-10-11 · Updated: 2026-10-11 · Language: en - Canonical page: https://hysenlabs.com/projects/lusingander-serie ## Images instead of ASCII art: how the git graph renders serie calls itself a TUI application but its core mechanism differs from most TUI tools. Rather than drawing a commit graph from ASCII characters, it uses the terminal emulator's image display protocol to render the graph as a pixel image inside the terminal window. The README describes this as a way to provide a rich git log --graph experience without the readability problems of text-based graphs. Two image protocols are supported: the Inline Images Protocol that iTerm2 uses, and kitty's Terminal Graphics Protocol, which serie supports in both the standard graphics mode and the Unicode placeholder mode. Because the graph is a rendered image, its quality depends on what the terminal can display, and not every terminal implements either protocol. The Rust image crate in Cargo.toml is configured with default-features = false and features = ["png"], which means only PNG format is enabled for image processing and all graph images are PNG internally. ## cargo install --locked serie requires Rust 1.88.0 or newer The README's installation section covers the Cargo route: ```bash cargo install --locked serie ``` The Cargo.toml sets rust-version to 1.88.0, so an older Rust toolchain will reject the build. The --locked flag pins the build to the exact dependency versions in Cargo.lock, which the Cargo.toml file specifies at the package level alongside a full dependency tree. For other installation methods, the README points to https://lusingander.github.io/serie/getting-started/installation.html. Once installed, run serie from inside any git repository directory: ```bash cd serie ``` Serie reads the git history and renders the commit graph in the terminal. The README does not document what happens when serie is run outside a git repository. ## Six CLI flags: image protocol, ordering, graph width, style and commit limit The command-line interface exposes 6 options beyond --help and --version. Each has a default that applies when the flag is omitted: ``` -n, --max-count Maximum number of commits to render -p, --protocol Image protocol to render graph [default: auto] [possible values: auto, iterm, kitty, kitty-unicode] -o, --order Commit ordering algorithm [default: chrono] [possible values: chrono, topo] -g, --graph-width Commit graph image cell width [default: auto] [possible values: auto, double, single] -s, --graph-style Commit graph image edge style [default: rounded] [possible values: rounded, angular] -i, --initial-selection Initial selection of commit [default: latest] [possible values: latest, head] ``` The --protocol flag is the one to check first on a new terminal. Setting it to auto lets serie detect the protocol, but when detection fails the graph will not render. Passing iterm, kitty or kitty-unicode forces a specific protocol and removes the guesswork. The --order flag controls whether commits sort by timestamp (chrono) or by topological order (topo). For repositories with active parallel branches, the difference is visible in how branch lines intersect on the graph. ## iTerm2 and kitty are the two supported image protocols; tmux only with kitty Unicode The compatibility list is narrow. Serie supports iTerm2's Inline Images Protocol and kitty's Terminal Graphics Protocol, including its Unicode placeholder variant. No other protocols appear in the supported list. Sixel graphics is explicitly listed as unsupported in the README. For users of terminal multiplexers, the situation is specific. tmux is partially supported, but only when using kitty's Unicode placeholder protocol. Other multiplexers, including screen and Zellij, are listed as unsupported. Windows is not officially supported. The README points to GitHub issue #147 for anyone who wants to investigate the current state of Windows compatibility, but the project's stated position is that Windows support is out of scope. This means serie is a practical tool for macOS users on iTerm2 or for any user on a kitty terminal, and a conditional tool for tmux users who specifically use kitty Unicode mode. Any other environment requires checking the compatibility documentation at https://lusingander.github.io/serie/getting-started/compatibility.html before expecting a working graph. ## User command: running git diff, vim and background tasks from inside serie The user command feature extends serie beyond a read-only viewer. From inside the TUI, a configured user command can run an external process in one of 3 modes. A display command runs something like git diff and shows its output in a dedicated view within serie. A background command runs something like a branch deletion command without leaving the TUI. An interactive command, such as vim, suspends serie and hands the terminal to the external process until it exits. The README does not give the config syntax for user commands inline; it points to https://lusingander.github.io/serie/features/user-command.html. The feature makes serie more than a commit log browser: with the right user commands configured, a developer can inspect diffs, delete branches and open commits in an editor without switching applications. Keybindings for all features, including user commands, are visible by pressing the ? key inside serie. The default keybindings can be overridden through a custom keybindings file documented separately. ## Config loads from $SERIE_CONFIG_FILE first, then $XDG_CONFIG_HOME/serie/config.toml Configuration follows a two-level priority chain. If the environment variable $SERIE_CONFIG_FILE is set, serie loads from that path. If $SERIE_CONFIG_FILE is set but the file does not exist, serie exits with an error rather than falling back. If $SERIE_CONFIG_FILE is not set at all, serie looks for $XDG_CONFIG_HOME/serie/config.toml. When $XDG_CONFIG_HOME is not set, ~/.config/ is used as the base. When no config file is found, serie uses default values for all settings. When a config file exists but does not set every item, the unset items fall back to defaults. This means an empty config file is valid and changes nothing, while a partial config file overrides only the items it specifies. The config file format is TOML, and the repository root includes a config.schema.json, which documents the schema for the config file and can be used with editors that support JSON Schema validation for TOML. ## Non-goals state: not a full git client, not a complex UI, and not Windows The README lists 3 explicit non-goals: serie does not aim to be a fully featured git client, does not aim for a complex UI, and does not aim to work in every terminal environment. These are project decisions rather than gaps, and they explain why the compatibility list stays narrow. The consequence is that serie does not replace tools like tig, lazygit or gitui for full repository management. It complements them: serie renders the commit graph, and those other tools handle staging, committing and branch operations. A developer who wants a single tool for everything will need to look elsewhere. The last push was on 2026-09-26 and the repository is not archived. The minimum Rust version of 1.88.0 is set in Cargo.toml, so an upgrade to a newer Rust edition in a future version could raise that floor. ## Conclusion serie suits developers who work in iTerm2 or a kitty-protocol terminal and want a commit graph viewer that renders as an actual image. Skip it when the workflow involves tmux with anything other than kitty Unicode, screen, Zellij, or Windows, since the README names those as unsupported or partially supported. Before adopting it for day-to-day use, run serie in a test repository to confirm the terminal's image protocol works: if protocol defaults to auto and the terminal is not on the supported list, the graph will not render correctly. ## FAQ ### What is serie? serie is a Rust TUI application that displays a git commit graph as a rendered image in the terminal, rather than as ASCII characters. It uses terminal image protocols (iTerm2 Inline Images Protocol or kitty Terminal Graphics Protocol) and is pronounced /zéːriə/. ### How do I install serie? Run cargo install --locked serie from a Rust environment that meets the minimum version of 1.88.0. For other installation options, the README points to the installation documentation at the project homepage. ### Does serie work in tmux? Partially. According to the README, tmux is supported only when using the kitty Unicode placeholder protocol. Other multiplexers such as screen and Zellij are listed as unsupported. ### Which terminal emulators support serie? serie supports the iTerm2 Inline Images Protocol and the kitty Terminal Graphics Protocol, including its Unicode placeholder mode. Sixel graphics is explicitly listed as unsupported. The compatibility documentation at the project site has the full list. ### Can I run external commands from inside serie? Yes, through the user command feature. Commands can run in display mode (showing output inside serie), background mode (running without leaving the TUI), or interactive mode (suspending serie and handing the terminal to the process). Configuration details are in the user command documentation at the project site. ## Sources - [License: MIT](https://github.com/lusingander/serie/blob/master/LICENSE) - [lusingander/serie on GitHub](https://github.com/lusingander/serie) - [Project website](https://lusingander.github.io/serie/) - [README](https://github.com/lusingander/serie/blob/master/README.md) - [Releases](https://github.com/lusingander/serie/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/lusingander-serie