Skip to content

A rich git commit graph in your terminal, like magic πŸ“š

License

Notifications You must be signed in to change notification settings

lusingander/serie

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 

History

55 Commits
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

Serie

Crate Status

A rich git commit graph in your terminal, like magic πŸ“š

(This demo shows Ratatui repository!)

About

Serie (/zéːriΙ™/) is a TUI application that uses the terminal emulators' image display protocol to render commit graphs like git log --graph --all.

Why?

While some users prefer to use Git via CLI, they often rely on a GUI or feature-rich TUI to view commit logs. Others may find git log --graph sufficient.

Personally, I found the output from git log --graph difficult to read, even with additional options. Learning complex tools just to view logs seemed cumbersome.

Goals

  • Provide a rich git log --graph experience in the terminal.
  • Offer commit graph-centric browsing of Git repositories.

Non-Goals

  • Implement a fully-featured Git client.
  • Create a TUI application with a complex UI.
  • Works in any terminal environment.

Requirements

  • Git
  • Supported terminal emulator

Installation

$ cargo install --locked serie
$ pacman -S serie
$ brew install lusingander/tap/serie
$ pkgin install serie

Downloading binary

You can download pre-compiled binaries from releases.

Build from source

If you want to check the latest development version, build from source:

$ git clone https://github.com/lusingander/serie.git
$ cd serie
$ cargo build --release # Unless it's a release build, it's very slow.
$ ./target/release/serie

Usage

Basic

Run serie in the directory where your git repository exists.

$ cd <your git repository>
$ serie

Options

Serie - A rich git commit graph in your terminal, like magic πŸ“š

Usage: serie [OPTIONS]

Options:
  -p, --protocol <TYPE>     Image protocol to render graph [default: auto] [possible values: auto, iterm, kitty]
  -o, --order <TYPE>        Commit ordering algorithm [default: chrono] [possible values: chrono, topo]
  -g, --graph-width <TYPE>  Commit graph image cell width [possible values: double, single]
      --preload             Preload all graph images
  -h, --help                Print help
  -V, --version             Print version

-p, --protocol <TYPE>

A protocol type for rendering images of commit graphs.

By default auto will guess the best supported protocol for the current terminal. Kitty terminals are detected as kitty via an environment variable, and all others are assumed to support iterm.

Refer to Compatibility for details.

-o, --order <TYPE>

--order chrono will order commits by commit date if possible.

--order topo will order commits on the same branch consecutively if possible.

Screenshots

--order chrono

--order topo

-g, --graph-width <TYPE>

The character width that a graph image unit cell occupies.

If not specified, double will be used automatically if there is enough width to display it, single otherwise.

Screenshots

--graph-width double

--graph-width single

--preload

By default, graph images are generated and loaded lazily as needed.

If --preload is specified, all graph images will be generated and loaded at startup. This can result in smoother scrolling, as the images are already available, and might reduce memory usage. However, this may lead to slower startup times, especially for large repositories.

Keybindings

You can see the keybindings by pressing the ? key.

The default key bindings can be overridden. Please refer to default-keybind.toml and add it to config file.

List of all default keybindings

Common

Key Description Corresponding keybind
Ctrl-c q Quit app force_quit quit
? Open help help_toggle

Commit List

Key Description Corresponding keybind
Down/Up j/k Move down/up navigate_down navigate_up
g/G Go to top/bottom go_to_top go_to_bottom
Ctrl-f/b Scroll page down/up page_down page_up
Ctrl-d/u Scroll half page down/up half_page_down half_page_up
H/M/L Select top/middle/bottom of the screen select_top select_middle select_bottom
Enter Show commit details
Apply search (if searching)
confirm
Tab Open refs list ref_list_toggle
/ Start search search
Esc Cancel search cancel
n/N Go to next/previous search match go_to_next go_to_previous
c/C Copy commit short/full hash short_copy full_copy

Commit Detail

Key Description Corresponding keybind
Esc Backspace Close commit details close cancel
Down/Up j/k Scroll down/up navigate_down navigate_up
g/G Go to top/bottom go_to_top go_to_bottom
c/C Copy commit short/full hash short_copy full_copy

Refs List

Key Description Corresponding keybind
Esc Backspace Tab Close refs list close cancel ref_list_toggle
Down/Up j/k Move down/up navigate_down navigate_up
g/G Go to top/bottom go_to_top go_to_bottom
Right/Left l/h Open/Close node navigate_right navigate_left
c Copy ref name short_copy

Help

Key Description Corresponding keybind
Esc Backspace ? Close help close cancel help_toggle
Down/Up j/k Scroll down/up navigate_down navigate_up
g/G Go to top/bottom go_to_top go_to_bottom

Config

Config files are loaded in the following order of priority:

  • $SERIE_CONFIG_FILE
    • If $SERIE_CONFIG_FILE is set but the file does not exist, an error occurs.
  • $XDG_CONFIG_HOME/serie/config.toml
    • If $XDG_CONFIG_HOME is not set, ~/.config/ will be used instead.

If the config file does not exist, the default values will be used for all items. If the config file exists but some items are not set, the default values will be used for those unset items.

Config file details

Config file format

The values set in this example are the default values.

[ui.list]
# The minimum width of a subject in the commit list.
# type: u16
subject_min_width = 20
# The date format of a author date in the commit list.
# The format must be specified in strftime format.
# https://docs.rs/chrono/latest/chrono/format/strftime/index.html
# type: string
date_format = "%Y-%m-%d"
# The width of a author date in the commit list.
# type: u16
date_width = 10
# Whether to show a author date in the commit list in local timezone.
# type: boolean
date_local = true
# The width of a author name in the commit list.
# type: u16
name_width = 20

[ui.detail]
# The height of a commit detail area.
# type: u16
height = 20
# The date format of a author/committer date in the commit detail.
# The format must be specified in strftime format.
# https://docs.rs/chrono/latest/chrono/format/strftime/index.html
# type: string
date_format = "%Y-%m-%d %H:%M:%S %z"
# Whether to show a author/committer date in the commit list in local timezone.
# type: boolean
date_local = true

[ui.refs]
# The width of a refs list area.
# type: u16
width = 26

[graph.color]
# Colors should be specified in the format #RRGGBB or #RRGGBBAA.

# Array of colors used for the commit graph.
# type: array of strings
branches = [
  "#E06C76",
  "#98C379",
  "#E5C07B",
  "#61AFEF",
  "#C678DD",
  "#56B6C2",
]
# Color of the edge surrounding the commit circles in the graph.
# type: string
edge = "#00000000"
# Background color of the commit graph.
# type: string
background = "#00000000"

[keybind]
# See ./assets/default-keybind.toml for a specific example configuration.
# ...

Compatibility

Supported terminals

These image protocols are supported:

The terminals on which each has been confirmed to work are listed below.

Inline Images Protocol

Terminal emulator Support Note
iTerm2 β—‹ But slower than other terminals
WezTerm β—‹
VSCode integrated terminal β—‹ Requires the terminal.integrated.enableImages setting to be enabled
Hyper β–³ >=v4.0.0, not yet officially released
Tabby β–³ The graph background is not transparent

Terminal graphics protocol

Terminal emulator Support Note
kitty β—‹

Terminal multiplexers

Terminal multiplexers (tmux, Zellij, etc.) are not supported.

Reporting Compatibility

Please share your experience with other terminal emulators on the Discussions.

Contributing

To get started with contributing, please review CONTRIBUTING.md.

Contributions that do not follow these guidelines may not be accepted.

Screenshots

The following repositories are used as these examples:

License

MIT