Add ASCII rendering fallback for terminals without image protocols

README.md

@@ -11,7 +11,7 @@ A rich git commit graph in your terminal, like magic 📚
 
 ## About
 
-Serie ([`/zéːriə/`](https://lusingander.github.io/serie/faq/index.html#how-do-i-pronounce-serie)) is a TUI application that uses the terminal emulators' image display protocol to render commit graphs like `git log --graph --all`.
+Serie ([`/zéːriə/`](https://lusingander.github.io/serie/faq/index.html#how-do-i-pronounce-serie)) is a TUI application that renders commit graphs like `git log --graph --all`, using a terminal emulator's image-display protocol for high-quality output where available and a Unicode box-drawing fallback in any other terminal.
 
 ### Why?
 
@@ -70,7 +70,7 @@ Usage: serie [OPTIONS]
 
 Options:
   -n, --max-count <NUMBER>        Maximum number of commits to render
-  -p, --protocol <TYPE>           Image protocol to render graph [default: auto] [possible values: auto, iterm, kitty, kitty-unicode]
+  -p, --protocol <TYPE>           Image protocol to render graph [default: auto] [possible values: auto, iterm, kitty, kitty-unicode, ascii]
   -o, --order <TYPE>              Commit ordering algorithm [default: chrono] [possible values: chrono, topo]
   -g, --graph-width <TYPE>        Commit graph image cell width [default: auto] [possible values: auto, double, single]
   -s, --graph-style <TYPE>        Commit graph image edge style [default: rounded] [possible values: rounded, angular]
@@ -112,17 +112,19 @@ For details on how to set commands, see [User Command](https://lusingander.githu
 
 ### Supported terminals
 
-These image protocols are supported:
+These rendering modes are supported:
 
 - [Inline Images Protocol (iTerm2)](https://iterm2.com/documentation-images.html)
 - [Terminal graphics protocol (kitty)](https://sw.kovidgoyal.net/kitty/graphics-protocol/)
   - Supports both the existing graphics protocol mode and the [Unicode placeholder](https://sw.kovidgoyal.net/kitty/graphics-protocol/#unicode-placeholders) mode.
+- ASCII / Unicode box-drawing fallback (works in any terminal)
+  - Used automatically when `auto` cannot identify a graphics-capable terminal, or selected explicitly with `--protocol ascii`.
 
 For more information, see [Compatibility](https://lusingander.github.io/serie/getting-started/compatibility.html).
 
 ### Partially supported environments
 
-- tmux is supported only when using the kitty Unicode placeholder protocol.
+- tmux is supported only when using the kitty Unicode placeholder protocol (image rendering) or the ASCII fallback.
 
 ### Unsupported environments
 

config.schema.json

@@ -14,12 +14,13 @@
           "properties": {
             "protocol": {
               "type": "string",
-              "description": "The protocol type for rendering images of commit graphs. The value specified in the command line argument takes precedence.",
+              "description": "The protocol used to render commit graphs. 'auto' autodetects the best available mode for the current terminal and falls back to 'ascii' when no graphics protocol is detected. The value specified in the command line argument takes precedence.",
               "enum": [
                 "auto",
                 "iterm",
                 "kitty",
-                "kitty-unicode"
+                "kitty-unicode",
+                "ascii"
               ],
               "default": "auto"
             },

docs/src/configurations/config-file-format.md

@@ -109,15 +109,16 @@ divider_fg = "dark-gray"
 
 ### `core.option.protocol`
 
-The protocol type for rendering images of commit graphs.
+The protocol used to render commit graphs.
 
 - type: `string` (enum)
 - default: `auto`
 - possible values:
-  - `auto`
-  - `iterm`
-  - `kitty`
-  - `kitty-unicode`
+  - `auto` — autodetect the best available mode for the current terminal. Selects an image protocol when one is detected (Kitty, Ghostty, iTerm2, WezTerm, mintty, VSCode); otherwise falls back to `ascii`.
+  - `iterm` — [iTerm2 inline images protocol](https://iterm2.com/documentation-images.html)
+  - `kitty` — [kitty graphics protocol](https://sw.kovidgoyal.net/kitty/graphics-protocol/)
+  - `kitty-unicode` — kitty graphics protocol with [Unicode placeholders](https://sw.kovidgoyal.net/kitty/graphics-protocol/#unicode-placeholders) (works under tmux)
+  - `ascii` — Unicode box-drawing fallback (`● │ ─ ╭ ╮ ╰ ╯`). Works in any terminal.
 
 The value specified in the command line argument takes precedence.
 

docs/src/faq/index.md

@@ -2,18 +2,18 @@
 
 ## Why doesn't the graph display?
 
-Serie displays graphs using specific terminal graphics protocols (such as Kitty and iTerm2 inline images).
+Serie renders graphs in one of two ways, depending on what your terminal supports:
 
-**If your terminal emulator doesn't support one of these protocols, Serie will not work — there is no fallback or workaround.**
+1. **High-quality images** via the Kitty or iTerm2 inline-image protocols, used automatically in terminals that support them.
+2. **Unicode box-drawing characters** (`● │ ─ ╭ ╮ ╰ ╯`), used in any other terminal as an automatic fallback.
 
-This is a fundamental requirement, not a limitation that can be worked around.
-For a list of supported terminal emulators and compatible environments, see [Compatibility](../getting-started/compatibility.md).
+If you see no graph at all, the most likely cause is that `auto` picked an image protocol your terminal does not actually support. Try `serie --protocol ascii` to force the Unicode fallback, or see [Compatibility](../getting-started/compatibility.md) for the list of terminals that support each image protocol.
 
 ## What are the advantages over other git TUI clients?
 
 Compared to other git TUI clients, Serie offers the following advantages:
 
-- High-quality graph visualization using terminal graphics protocols
+- High-quality graph visualization using terminal graphics protocols (with a Unicode fallback for terminals that lack them)
 - Simple and clean interface
 
 On the other hand, Serie may not be for you if:

docs/src/getting-started/command-line-options.md

@@ -9,11 +9,17 @@ It behaves similarly to the `--max-count` option of `git log`.
 
 ## -p, --protocol \<TYPE\>
 
-A protocol type for rendering images of commit graphs.
+The protocol used to render commit graphs.
 
-_Possible values:_ `auto`, `iterm`, `kitty`, `kitty-unicode`
+_Possible values:_ `auto`, `iterm`, `kitty`, `kitty-unicode`, `ascii`
 
-By default `auto` will guess the best supported protocol for the current terminal (if listed in [Supported terminal emulators](./compatibility.md#supported-terminal-emulators)).
+By default `auto` will pick the best supported mode for the current terminal:
+
+1. Kitty graphics protocol if `KITTY_WINDOW_ID`, `GHOSTTY_RESOURCES_DIR`, or `TERM=xterm-ghostty` is set (uses the Unicode-placeholder variant under tmux).
+2. iTerm2 inline images if `TERM_PROGRAM` is `iTerm.app`, `WezTerm`, `mintty`, or `vscode`, or if `LC_TERMINAL=iTerm2`.
+3. Otherwise the `ascii` fallback, which uses Unicode box-drawing characters and works in any terminal.
+
+The `ascii` value can also be selected explicitly — useful if `auto` misidentifies your terminal or if you just want plain text. ASCII rendering honors `--graph-style rounded|angular` (corner glyphs) and `--graph-width single|double` (single character per branch column, or two characters with `●`/`○` and arrow markers on merge commits).
 
 ## -o, --order \<TYPE\>
 

docs/src/getting-started/compatibility.md

@@ -2,13 +2,14 @@
 
 ## Supported terminal emulators
 
-These image protocols are supported:
+Serie supports three rendering modes:
 
-- [Inline Images Protocol (iTerm2)](https://iterm2.com/documentation-images.html)
-- [Terminal graphics protocol (kitty)](https://sw.kovidgoyal.net/kitty/graphics-protocol/)
+- [Inline Images Protocol (iTerm2)](https://iterm2.com/documentation-images.html) — high-quality PNG images
+- [Terminal graphics protocol (kitty)](https://sw.kovidgoyal.net/kitty/graphics-protocol/) — high-quality PNG images
   - Supports both the existing graphics protocol mode and [the Unicode placeholder](https://sw.kovidgoyal.net/kitty/graphics-protocol/#unicode-placeholders) mode.
+- **ASCII / Unicode box-drawing fallback** — works in any terminal (gnome-terminal, alacritty, xterm, Windows Terminal, etc.). Used automatically when `auto` cannot identify a graphics-capable terminal, or by passing `--protocol ascii`.
 
-The terminals on which each has been confirmed to work are listed below.
+The terminals on which each image protocol has been confirmed to work are listed below.
 
 ### Inline Images Protocol
 
@@ -30,13 +31,24 @@ The terminals on which each has been confirmed to work are listed below.
 
 Rendering using Unicode Placeholder is available by explicitly specifying `kitty-unicode` as `protocol` option or config.
 
+### ASCII fallback
+
+The `ascii` protocol renders graphs with Unicode box-drawing characters and works in any terminal — no image protocol required. Auto-detect falls back to this mode when none of the image protocols above can be identified.
+
+It honors:
+
+- `--graph-style rounded` (default) — uses `╭ ╮ ╰ ╯` for corners.
+- `--graph-style angular` — uses `┌ ┐ └ ┘` for corners.
+- `--graph-width single` — one character per branch column.
+- `--graph-width double` — two characters per branch column, with `○` and `> / <` arrow markers on merge commits.
+
 ### Partially supported environments
 
-- tmux is supported only when using the kitty Unicode placeholder protocol.
-  - Requires `set -g allow-passthrough on` in tmux.conf (version 3.2+).
+- tmux is supported when using the kitty Unicode placeholder protocol (`kitty-unicode`) or the ASCII fallback (`ascii`). It is not supported with the plain `kitty` or `iterm` image protocols.
+  - The kitty Unicode placeholder requires `set -g allow-passthrough on` in tmux.conf (version 3.2+). The ASCII fallback has no special requirements.
 
 ### Unsupported environments
 
-- Sixel graphics is not supported.
-- Other terminal multiplexers (screen, Zellij, etc.) other than those listed in [Partially supported environments](#partially-supported-environments) are not supported.
+- Sixel graphics is not supported (for image rendering). The `ascii` fallback still works.
+- Other terminal multiplexers (screen, Zellij, etc.) are not supported for image rendering. The `ascii` fallback still works.
 - Windows is not officially supported. Please refer to [the related issue](https://github.com/lusingander/serie/issues/147#issuecomment-4192875627).

docs/src/introduction/index.md

@@ -1,6 +1,6 @@
 # Introduction
 
-**Serie** ([`/zéːriə/`](https://lusingander.github.io/serie/faq/index.html#how-do-i-pronounce-serie)) is a TUI application that uses the terminal emulators' image display protocol to render commit graphs like `git log --graph --all`.
+**Serie** ([`/zéːriə/`](https://lusingander.github.io/serie/faq/index.html#how-do-i-pronounce-serie)) is a TUI application that renders commit graphs like `git log --graph --all`, using a terminal emulator's image-display protocol for high-quality output where available and a Unicode box-drawing fallback in any other terminal.
 
 <img src="https://raw.githubusercontent.com/lusingander/serie/master/img/demo.gif">