Skip to content

Latest commit

 

History

History
279 lines (200 loc) · 8.48 KB

themes.md

File metadata and controls

279 lines (200 loc) · 8.48 KB

Theme Customization Guide

gitlogue provides a rich theming system with 15 beautiful built-in themes and support for custom theme configuration.

Table of Contents

Built-in Themes

gitlogue comes with 15 carefully crafted themes optimized for code readability and visual appeal:

Dark Themes

  • ayu-dark - Minimalist theme with clean design and orange accents. Simple and uncluttered.
  • catppuccin - Soothing pastel theme (Mocha variant) with soft, gentle colors.
  • dracula - Vibrant dark theme with rich purples and greens. High contrast for extended viewing.
  • everforest - Nature-inspired theme with earthy green tones. Easy on the eyes for long sessions.
  • github-dark - GitHub's official dark theme. Clean and professional for familiar coding experience.
  • gruvbox - Retro groove color scheme with warm, earthy tones. Perfect for a cozy coding atmosphere.
  • material - Google's Material Design inspired theme. Modern and vibrant color palette.
  • monokai - Classic theme with warm browns and oranges. Reminiscent of vintage terminals.
  • night-owl - Deep blue theme designed for night owls. Carefully balanced contrast for extended use.
  • nord - Cool, arctic-inspired color palette with muted blues and grays. Smooth and calming.
  • one-dark - Inspired by Atom's One Dark theme. Clean and professional with excellent syntax highlighting.
  • rose-pine - Elegant pastel theme with purple and pink tones. Soft and sophisticated color scheme.
  • solarized-dark - The legendary Solarized theme (dark variant). Scientifically designed for optimal readability.
  • tokyo-night (default) - Modern dark theme inspired by Tokyo's neon nights. Balanced contrast with blue and purple accents.

Light Themes

  • solarized-light - The popular Solarized theme (light variant). Perfect for well-lit environments.

Using Themes

Listing Available Themes

To see all available themes with descriptions:

gitlogue theme list

This command displays:

  • Theme names
  • Brief descriptions
  • Whether they are dark or light themes

Selecting a Theme

Via Command Line

Use the --theme option to specify a theme for a single session:

gitlogue --theme dracula
gitlogue --theme nord
gitlogue --theme solarized-light

Examples:

# Use Dracula theme for current directory
gitlogue --theme dracula

# View a specific commit with Nord theme
gitlogue --commit abc123 --theme nord

# Slower typing with Gruvbox theme
gitlogue --speed 50 --theme gruvbox

# Use Material theme with transparent background
gitlogue --theme material --background false

Via Configuration File

Note: Configuration file support is planned for a future release and is not yet available.

Once implemented, you'll be able to set a default theme in ~/.config/gitlogue/config.toml.

Background Options

All themes support transparent backgrounds, allowing you to use your terminal's background (including transparency and background images).

Using Transparent Background

Use --background false or --background=false to disable theme background colors:

# Use transparent background with any theme
gitlogue --background false
gitlogue --background=false

# Combine with specific theme
gitlogue --theme rose-pine --background false
gitlogue --theme github-dark --background=false

Using Opaque Background (Default)

By default, themes use their defined background colors:

# Default behavior - background colors enabled
gitlogue
gitlogue --theme dracula

Benefits of Transparent Background

  • Works with terminal transparency settings
  • Shows your terminal background image
  • Integrates seamlessly with your desktop environment
  • Reduces visual clutter in tiling window managers

Note: Transparent background only affects the main background areas. UI elements like cursor highlights and selected file backgrounds remain visible for usability.

Creating Custom Themes

Note: Custom theme support is planned for future releases and is not yet available in the current version.

Custom themes will be loaded from the ~/.config/gitlogue/themes/ directory and support both JSON and TOML formats.

Planned Features

  • Load themes from ~/.config/gitlogue/themes/
  • Support for TOML and JSON format
  • Hot-reloading during development
  • Theme validation and error reporting
  • Theme sharing via GitHub gists

Theme Structure

A gitlogue theme defines colors for all UI components:

UI Components

  • Background colors: Left panel (file tree) and right panel (editor) backgrounds
  • Editor colors: Line numbers, cursor, separators, selection
  • File tree colors: Status indicators (added, deleted, modified, renamed)
  • Terminal colors: Command input, output, cursor, prompt
  • Status bar colors: Commit hash, author, date, message
  • Syntax highlighting colors: Keywords, types, functions, strings, comments, operators, etc.

Example Theme File Structure (TOML)

# ~/.config/gitlogue/themes/my-theme.toml

name = "My Custom Theme"
description = "A beautiful custom theme"
author = "Your Name"
variant = "dark"  # or "light"

[background]
left = { r = 30, g = 34, b = 54 }
right = { r = 26, g = 27, b = 38 }

[editor]
line_number = { r = 86, g = 95, b = 137 }
line_number_cursor = { r = 125, g = 207, b = 255 }
cursor_char_bg = { r = 122, g = 162, b = 247 }
cursor_char_fg = { r = 26, g = 27, b = 38 }
separator = { r = 50, g = 54, b = 74 }

[file_tree]
added = { r = 158, g = 206, b = 106 }
deleted = { r = 247, g = 118, b = 142 }
modified = { r = 255, g = 158, b = 100 }
renamed = { r = 125, g = 207, b = 255 }

[terminal]
command_input = { r = 169, g = 177, b = 214 }
command_output = { r = 192, g = 202, b = 245 }
cursor = { r = 125, g = 207, b = 255 }

[status_bar]
hash = { r = 187, g = 154, b = 247 }
author = { r = 125, g = 207, b = 255 }
date = { r = 255, g = 158, b = 100 }
message = { r = 192, g = 202, b = 245 }

[syntax]
keyword = { r = 187, g = 154, b = 247 }
type = { r = 125, g = 207, b = 255 }
function = { r = 130, g = 170, b = 255 }
string = { r = 158, g = 206, b = 106 }
number = { r = 255, g = 158, b = 100 }
comment = { r = 86, g = 95, b = 137 }
operator = { r = 187, g = 154, b = 247 }
variable = { r = 169, g = 177, b = 214 }
constant = { r = 255, g = 158, b = 100 }

Color Format

Colors are specified as RGB values with components ranging from 0 to 255:

color_name = { r = 255, g = 100, b = 50 }

Choosing the Right Theme

For Long Sessions

  • everforest - Nature-inspired greens, very easy on the eyes
  • nord - Muted colors with arctic coolness
  • rose-pine - Soft pastels for comfortable viewing
  • catppuccin - Gentle and soothing tones

For High Contrast

  • dracula - Vibrant purples and greens
  • material - Bold, modern colors
  • solarized-dark - Scientifically optimized contrast

For Minimalists

  • ayu-dark - Clean and simple design
  • github-dark - Familiar and uncluttered
  • one-dark - Professional and minimal

For Night Coding

  • night-owl - Designed specifically for night use
  • tokyo-night - Modern with balanced contrast
  • monokai - Classic warm tones

For Bright Environments

  • solarized-light - Optimized for well-lit spaces

For Retro Aesthetics

  • gruvbox - Warm, earthy retro groove
  • monokai - Classic vintage terminal feel

Troubleshooting

Theme Not Loading

If your theme isn't applied:

  1. Check the theme name is correct:

    gitlogue theme list

  2. Verify the theme name spelling (case-sensitive with hyphens):

    • Use tokyo-night, not tokyo_night or TokyoNight

  3. Try specifying the theme explicitly:

    gitlogue --theme tokyo-night

Colors Look Wrong

If colors appear incorrect:

  1. Check your terminal's color support:

    echo $TERM

  2. Ensure your terminal supports 24-bit colors (truecolor)

  3. Try a different terminal emulator if colors still look wrong

Next Steps

Feedback

Have ideas for new themes? Open an issue or pull request on GitHub!