Skip to content

Consolidate recent theme change docs in THEMES.md #2575

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Mar 22, 2025
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 29 additions & 3 deletions THEMES.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,8 @@
default on light terminal:
![](assets/light-theme.png)

## Configuration

To change the colors of the default theme you need to add a `theme.ron` file that contains the colors you want to override. Note that you don’t have to specify the full theme anymore (as of 0.23). Instead, it is sufficient to override just the values that you want to differ from their default values.

The file uses the [Ron format](https://github.com/ron-rs/ron) and is located at one of the following paths, depending on your operating system:
Expand All @@ -16,7 +18,7 @@ Alternatively, you can create a theme in the same directory mentioned above and

Example theme override:

```
```ron
(
selection_bg: Some("Blue"),
selection_fg: Some("#ffffff"),
Expand All @@ -32,19 +34,43 @@ Notes:
* valid colors can be found in ratatui's [Color](https://docs.rs/ratatui/latest/ratatui/style/enum.Color.html) struct.
* all customizable theme elements can be found in [`style.rs` in the `impl Default for Theme` block](https://github.com/gitui-org/gitui/blob/master/src/ui/style.rs#L305)

## Preset Themes

You can find preset themes by Catppuccin [here](https://github.com/catppuccin/gitui.git).

## Syntax Highlighting

The syntax highlighting theme can be defined using the element `syntax`. Both [default themes of the syntect library](https://github.com/trishume/syntect/blob/7fe13c0fd53cdfa0f9fea1aa14c5ba37f81d8b71/src/dumps.rs#L215) and custom themes are supported.

Example syntax theme:
```ron
(
syntax: Some("InspiredGitHub"),
)
```

Custom themes are located in the [configuration directory](#configuration), are using TextMate's theme format and must have a `.tmTheme` file extension. To load a custom theme, `syntax` must be set to the file name without the file extension. For example, to load [`Blackboard.tmTheme`](https://raw.githubusercontent.com/filmgirl/TextMate-Themes/refs/heads/master/Blackboard.tmTheme), place the file next to `theme.ron` and set:
```ron
(
syntax: Some("Blackboard"),
)
```

[filmgirl/TextMate-Themes](https://github.com/filmgirl/TextMate-Themes) offers many [beautiful](https://inkdeep.github.io/TextMate-Themes) TextMate themes to choose from.

## Customizing line breaks

If you want to change how the line break is displayed in the diff, you can also specify `line_break` in your `theme.ron`:

```
```ron
(
line_break: Some("¶"),
)
```

Note that if you want to turn it off, you should use a blank string:

```
```ron
(
line_break: Some(""),
)
Expand Down