Skip to content

configuration.md

Latest commit

 

History

History
325 lines (224 loc) · 7.58 KB

configuration.md

File metadata and controls

325 lines (224 loc) · 7.58 KB

Configuration Guide

gitlogue supports configuration via a TOML file located at ~/.config/gitlogue/config.toml.

All configuration options are optional. CLI arguments take precedence over config file values.

Quick Start

Set your default theme using the theme set command:

gitlogue theme set dracula

Or manually create/edit the config file:

# Create config directory
mkdir -p ~/.config/gitlogue

# Edit config file
vim ~/.config/gitlogue/config.toml

Configuration File Format

The config file uses TOML format. Here's a complete example:

# gitlogue configuration file
# All settings are optional and will use defaults if not specified

# Theme to use for syntax highlighting
theme = "dracula"

# Typing speed in milliseconds per character
speed = 50

# Show background colors (set to false for transparent background)
background = true

# Commit playback order: random, asc, or desc
order = "random"

# Loop the animation continuously
loop = false

# Ignore patterns (gitignore syntax)
# Examples: ["*.ipynb", "poetry.lock", "docs/api/**"]
ignore_patterns = []

# Speed rules for different file types (pattern:milliseconds)
# Examples: ["*.java:50", "*.xml:5", "*.rs:30"]
speed_rules = []

Configuration Options

theme

Theme name for syntax highlighting.

  • Type: String
  • Default: "tokyo-night"
  • Example: theme = "dracula"

See all available themes:

gitlogue theme list

Available themes: ayu-dark, catppuccin, dracula, everforest, github-dark, gruvbox, material, monokai, night-owl, nord, one-dark, rose-pine, solarized-dark, solarized-light, tokyo-night

speed

Typing speed in milliseconds per character. Lower values = faster typing animation.

  • Type: Integer
  • Default: 30
  • Range: Typically 10-100
  • Example: speed = 20

background

Whether to show background colors in themes.

  • Type: Boolean
  • Default: true
  • Example: background = false

Set to false for transparent background (useful for terminal transparency).

order

Commit playback order.

  • Type: String
  • Default: "random"
  • Example: order = "asc"

Available orders:

  • random - Randomly selects commits (default)
  • asc - Replays commits from oldest to newest
  • desc - Replays commits from newest to oldest

loop

Whether to loop the animation continuously.

  • Type: Boolean
  • Default: false
  • Example: loop = true

When enabled, the animation will repeat indefinitely after completing. Especially useful with specific commits for demonstrations and ambient displays.

ignore_patterns

List of patterns for files to ignore during animation.

  • Type: Array of strings
  • Default: [] (empty array)
  • Example: ignore_patterns = ["*.ipynb", "poetry.lock"]

Pattern syntax (gitignore-style):

  • *.ipynb - All Jupyter notebook files anywhere in the repository
  • poetry.lock - Poetry lock file in repository root
  • docs/api/** - All files under docs/api directory

Note: Binary files (images, videos, etc.) are already automatically excluded and don't need to be specified here.

Common use cases:

# Ignore Jupyter notebooks (JSON format, hard to read as text diff)
ignore_patterns = ["*.ipynb"]

# Ignore lock files that are tracked in git
ignore_patterns = ["poetry.lock", "Cargo.lock", "yarn.lock"]

# Ignore generated documentation
ignore_patterns = ["docs/api/**"]

# Combine multiple patterns
ignore_patterns = [
    "*.ipynb",
    "poetry.lock",
    "**/*.test.js",
    "**/__snapshots__/**"
]

Note: These patterns are additive with CLI --ignore flags and --ignore-file options. The ignore order is:

  1. Config file ignore_patterns
  2. --ignore-file patterns
  3. CLI --ignore flags (highest priority)

speed_rules

List of file-specific typing speed rules. Each rule specifies a glob pattern and speed in milliseconds.

  • Type: Array of strings
  • Default: [] (empty array)
  • Format: "PATTERN:MILLISECONDS"
  • Example: speed_rules = ["*.java:50", "*.xml:5"]

The first matching rule wins. Files that don't match any rule use the base speed setting.

Common use cases:

# Slow down for important source files, speed through configs
speed_rules = [
    "*.java:50",     # 50ms per char for Java (slower, more readable)
    "*.rs:40",       # 40ms per char for Rust
    "*.xml:5",       # 5ms per char for XML (fast)
    "*.json:5",      # 5ms per char for JSON (fast)
    "*.yaml:10",     # 10ms per char for YAML
]

# Focus on specific directories
speed_rules = [
    "src/**/*.ts:30",    # Slower for source TypeScript
    "tests/**/*.ts:10",  # Faster for test files
]

Note: CLI --speed-rule flags take priority over config file rules. Rules are evaluated in order (CLI first, then config).

Configuration Priority

Settings are applied in the following order (highest priority first):

  1. CLI arguments - Command-line flags override everything

    gitlogue --theme nord --speed 20 --background=false --order asc --loop --speed-rule "*.rs:50"

  2. Configuration file - Values from ~/.config/gitlogue/config.toml

  3. Default values - Built-in defaults if nothing else is specified

Example

Given this config file:

theme = "dracula"
speed = 50

Running this command:

gitlogue --speed 20

Will use:

  • theme = "dracula" (from config)
  • speed = 20 (from CLI, overrides config)
  • background = true (default value)

Managing Configuration

Using the theme set Command

The theme set command updates your config file while preserving comments:

# Set theme to nord
gitlogue theme set nord

# Your config file comments are preserved
cat ~/.config/gitlogue/config.toml
# Output:
# My custom comment here
theme = "nord"
speed = 50

Manual Editing

You can also edit the config file directly:

vim ~/.config/gitlogue/config.toml

Add your own comments for documentation:

# I prefer darker themes for night coding
theme = "tokyo-night"

# Slower speed for demos
speed = 50

# Transparent background for my terminal setup
background = false

Comment Preservation

gitlogue uses toml_edit to preserve all comments when updating the config file via commands:

  • Block comments above settings
  • Inline comments after values
  • Custom user comments
  • Formatting and whitespace

This means you can document your preferences in the config file without losing them when using theme set.

Troubleshooting

Config file not found

If the config file doesn't exist, gitlogue will use default values. You can create it:

mkdir -p ~/.config/gitlogue
cat > ~/.config/gitlogue/config.toml << 'EOF'
theme = "tokyo-night"
speed = 30
background = true
order = "random"
loop = false
ignore_patterns = []
speed_rules = []
EOF

Or use theme set to create it automatically:

gitlogue theme set tokyo-night

Invalid TOML syntax

If your config file has syntax errors, gitlogue will show an error message. Validate your TOML:

# Check syntax
cat ~/.config/gitlogue/config.toml

Common mistakes:

  • Missing quotes around string values: theme = dracula ❌ → theme = "dracula" ✅
  • Wrong boolean syntax: background = True ❌ → background = true ✅

Theme not found

If you set an invalid theme name:

gitlogue theme set invalid-theme
# Error: Unknown theme: invalid-theme
# Available themes: ayu-dark, catppuccin, dracula, ...

The config file won't be updated. Use gitlogue theme list to see available themes.

Related