serie - Visualize Git Commit Graphs in the Terminal with Serie

Introduction to Serie

Serie is a terminal-based application designed to enhance your experience when viewing Git commit logs. By leveraging the terminal emulator's image display protocol, Serie offers an enriched display of commit graphs, similar to the git log --graph --all command in Git. Through Serie, users can enjoy a GUI-like experience, simplifying the process of tracking changes in repositories.

Why Serie?

For users who utilize Git via the command line, viewing commit logs using graphical or text-based interfaces is sometimes preferred for clarity. While the git log --graph command is available, it can often produce cluttered outputs that are hard to interpret. Serie was created to address this issue by providing a more accessible and visual method of exploring commit histories, negating the need for learning overly complex tools.

Objectives and Non-Objectives

Serie focuses on offering an enhanced user experience for viewing git log --graph in the terminal, concentrating on commit graph browsing functionalities. However, it is not intended to be a comprehensive Git client, nor does it aim to produce a complex user interface. The aim is for it to be versatile enough to function in various terminal environments.

System Requirements

To make the most out of Serie, you’ll need:

Git installed on your system.
A compatible terminal emulator that supports image rendering (details in the Compatibility section).

How to Install Serie

You can install Serie through various platforms:

Cargo:
```
$ cargo install --locked serie
```
Arch Linux:
```
$ pacman -S serie
```
Homebrew (macOS):
```
$ brew install lusingander/tap/serie
```
NetBSD:
```
$ pkgin install serie
```

Alternatively, you can directly download pre-compiled binaries from Serie's releases page or build it from the source code for the latest developments.

Usage

To start using Serie, navigate to your Git repository's directory and run the following command:

$ serie

Configurations and Options

Serie offers different options to customize its behavior:

Protocol Type: To set the image protocol for rendering, use -p or --protocol.
Order Type: Use -o or --order to select between chronological (chrono) or topological (topo) commit ordering.
Graph Width: Set character width with -g or --graph-width.
Preload: Enable --preload to preload all graph images for smoother navigation at the cost of longer startup times in large repositories.

Enhancing Usage with Keybindings

Serie includes keybindings to streamline navigation and usage. For instance:

Common Commands: <Ctrl-c> to quit, ? to access help.
Commit List Navigation: <Down/Up> to scroll and <Enter> for commit details.
Commit Detail Views and Refs List also follow intuitive key commands.

For a complete list of keybindings and configuration instructions, please refer to Serie's comprehensive documentation.

Compatibility

Serie supports various image protocols compatible with select terminal emulators:

Inline Images Protocol (iTerm2)
Terminal Graphics Protocol (kitty)

Popular terminal emulators like iTerm2, WezTerm, and VSCode's integrated terminal have been tested for compatibility.

Contributing and Community Engagement

The Serie project welcomes contributions, and guidelines are available in the CONTRIBUTING.md file. Users can share experiences and report compatibility findings through the Serie community discussions.

By focusing on simplifying commit graph exploration, Serie stands out as a valuable tool for developers who seek a richer and more intuitive way of traversing Git logs without leaving the comfort of their terminal.