(This demo shows [Ratatui](https://github.com/ratatui/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
- Refer to [Compatibility](#compatibility) for details.
## Installation
### [Cargo](https://crates.io/crates/serie)
```
$ cargo install --locked serie
```
### [Arch Linux](https://archlinux.org/packages/extra/x86_64/serie/)
```
$ pacman -S serie
```
### [Homebrew](https://formulae.brew.sh/formula/serie)
```
$ brew install serie
```
or from [tap](https://github.com/lusingander/homebrew-tap/blob/master/serie.rb):
```
$ brew install lusingander/tap/serie
```
### [NetBSD](https://pkgsrc.se/devel/serie)
```
$ pkgin install serie
```
### Downloading binary
You can download pre-compiled binaries from [releases](https://github.com/lusingander/serie/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 Screenshots
`--order chrono`
`--order topo`
Screenshots
`--graph-width double`
`--graph-width single`
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` | | Alt-Down Alt-j | Move to parent commit | `go_to_parent` | | 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` | | Ctrl-e/y | Scroll down/up | `scroll_down` `scroll_up` | | H/M/L | Select top/middle/bottom of the screen | `select_top` `select_middle` `select_bottom` | | Enter | Show commit detailsApply 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` | | Ctrl-g | Toggle ignore case (if searching) | `ignore_case_toggle` | | Ctrl-x | Toggle fuzzy match (if searching) | `fuzzy_toggle` | | c/C | Copy commit short/full hash | `short_copy` `full_copy` | | d | Toggle custom user command view | `user_command_view_toggle_1` | #### Commit Detail | Key | Description | Corresponding keybind | | ----------------------------------- | ------------------------------- | ------------------------------- | | Esc Backspace | Close commit details | `close` `cancel` | | Down/Up j/k | Scroll down/up | `navigate_down` `navigate_up` | | 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` | | g/G | Go to top/bottom | `go_to_top` `go_to_bottom` | | c/C | Copy commit short/full hash | `short_copy` `full_copy` | | d | Toggle custom user command view | `user_command_view_toggle_1` | #### 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` | #### User Command | Key | Description | Corresponding keybind | | ------------------------------------------------ | ------------------------ | ------------------------------- | | Esc Backspace ? | Close user command | `close` `cancel` `help_toggle` | | Down/Up j/k | Scroll down/up | `navigate_down` `navigate_up` | | 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` | | g/G | Go to top/bottom | `go_to_top` `go_to_bottom` | #### Help | Key | Description | Corresponding keybind | | ------------------------------------------------ | ------------------------ | ------------------------------- | | Esc Backspace ? | Close help | `close` `cancel` `help_toggle` | | Down/Up j/k | Scroll down/up | `navigate_down` `navigate_up` | | 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` | | g/G | Go to top/bottom | `go_to_top` `go_to_bottom` |
Config file details
#### Config file format The values set in this example are the default values. ```toml [core.option] # The protocol type for rendering images of commit graphs. # The value specified in the command line argument takes precedence. # type: enum (possible values: "auto", "iterm", "kitty") protocol = "auto" # The commit ordering algorithm. # The value specified in the command line argument takes precedence. # type: enum (possible values: "chrono", "topo") order = "chrono" # The character width that a graph image unit cell occupies. # The value specified in the command line argument takes precedence. # type: enum (possible values: "auto", "double", "single") graph_width = "auto" [core.search] # Whether to enable ignore case by default. # type: boolean ignore_case = false # Whether to enable fuzzy matching by default. # type: boolean fuzzy = false [core.user_command] # The command definition for generating the content displayed in the user command view. # Multiple commands can be specified in the format commands_{n}. # For details about user command, see the separate User command section. # type: object commands_1 = { name = "git diff", commands = ["git", "--no-pager", "diff", "--color=always", "{{first_parent_hash}}", "{{target_hash}}"]} # The number of spaces to replace tabs in the user command output. # type: u16 tab_width = 4 [ui.common] # The type of a cursor to display in the input. # If `cursor_type = "Native"` is set, the terminal native cursor is used. # If `cursor_type = { "Virtual" = "|" }` is set, a virtual cursor with the specified string will be used. # type: enum cursor_type = "Native" [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.user_command] # The height of a user command area. # type: u16 height = 20 [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" [color] # The colors of each element of the application. # Note: Graph colors are specified with [graph.color]. # # Colors should be specified in one of the following formats: # - ANSI color name # - "red", "bright-blue", "light-red", "reset", ... # - 8-bit color (256-color) index values # - "34", "128", "255", ... # - 24-bit true color hex codes # - "#abcdef", ... # type: string fg = "reset" bg = "reset" list_selected_fg = "white" list_selected_bg = "dark-gray" list_ref_paren_fg = "yellow" list_ref_branch_fg = "green" list_ref_remote_branch_fg = "red" list_ref_tag_fg = "yellow" list_ref_stash_fg = "magenta" list_head_fg = "cyan" list_subject_fg = "reset" list_name_fg = "cyan" list_hash_fg = "yellow" list_date_fg = "magenta" list_match_fg = "black" list_match_bg = "yellow" detail_email_fg = "blue" detail_ref_branch_fg = "green" detail_ref_remote_branch_fg = "red" detail_ref_tag_fg = "yellow" detail_file_change_add_fg = "green" detail_file_change_modify_fg = "yellow" detail_file_change_delete_fg = "red" detail_file_change_move_fg = "magenta" ref_selected_fg = "white" ref_selected_bg = "dark-gray" help_block_title_fg = "green" help_key_fg = "yellow" virtual_cursor_fg = "reset" status_input_fg = "reset" status_input_transient_fg = "dark-gray" status_info_fg = "cyan" status_success_fg = "green" status_warn_fg = "yellow" status_error_fg = "red" divider_fg = "dark-gray" [keybind] # See ./assets/default-keybind.toml for a specific example configuration. # ... ```Configuration example
```toml [keybind] user_command_view_toggle_1 = ["d"] user_command_view_toggle_2 = ["shift-d"] [core.user_command] commands_1 = { "name" = "git diff", commands = ["git", "--no-pager", "diff", "--color=always", "{{first_parent_hash}}", "{{target_hash}}"] } commands_2 = { "name" = "xxx", commands = ["xxx", "{{first_parent_hash}}", "{{target_hash}}", "--width", "{{area_width}}", "--height", "{{area_height}}"] } ```
The following repositories are used as these examples:
- [ratatui/ratatui](https://github.com/ratatui/ratatui)
- [charmbracelet/vhs](https://github.com/charmbracelet/vhs)
- [lusingander/stu](https://github.com/lusingander/stu)
## License
MIT