# Modern ZSH Theme

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux-blue)](https://github.com/BadRat-in/zsh-modern-theme)
[![Shell](https://img.shields.io/badge/shell-zsh-green)](https://www.zsh.org/)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/BadRat-in/zsh-modern-theme/pulls)

A sleek and modern ZSH theme that automatically adapts to light and dark terminal themes.
This theme provides a clean and informative prompt with git integration, command execution time, virtualenv awareness, and a beautiful rainbow directory path.

## Table of Contents

- [Prompt Layout](#prompt-layout)
- [Key Features](#key-features-shortened)
- [Quick Start](#quick-start)
- [Installation](#installation)
- [Customization](#customization)
  - [Configuration File](#configuration-file)
  - [Duration Format](#1-duration-format)
  - [Git Configuration](#2-git-configuration)
  - [Virtual Environment](#3-virtual-environment)
  - [Time Display](#4-time-display)
  - [Example Configurations](#example-configurations)
  - [Colors](#colors)
  - [Git Symbols](#git-symbols)
- [FAQ](#faq)
- [Contributing](#contributing)
- [License](#license)
- [Author](#author)
- [Additional Resources](#additional-resources)

## Prompt Layout

Here’s how the prompt looks in action:

![Theme Preview Dark](screenshots/dark-theme.png)
![Theme Preview Light](screenshots/light-theme.png)

### Legend

- **👤 ravindra@\~**
  - `ravindra` = username (yellow)
  - `~` = home directory root (rainbow-colored)

- **🌈 \~/Projects/zsh-modern-theme**
  Rainbow-colored directory path for quick readability.
  - Each path segment = different color
  - `~` replaces `$HOME` and is rainbow-colored

- **🐍 env:(.venv)**
  Active Python virtual environment.
  - Shown only if a venv is active

- **🔄 git:(master) ✓**
  Git integration:
  - Branch name (purple)
  - ✓ = clean repo (green)
  - ✗ = dirty repo (red)

- **⏱️ 11:57:08 ⌛ 0s**
  Right-aligned time and command execution duration:
  - Current time (`%*`)
  - ⌛ + elapsed time of last command
  - Falls back to `[s]` if Unicode isn’t supported

- **❯**
  Prompt symbol:
  - Green ❯ = last command succeeded
  - Red ❯ = last command failed

## Key Features (shortened)

- 🌗 Auto light/dark detection
- 🌈 Rainbow directory path with `~` for home
- 🔄 Git branch + status (✓/✗)
- ⏱️ Time + command duration (⌛ / \[s])
- 🐍 Python venv awareness
- 👤 Username context
- ❌ Success/error colored prompt arrow
- 🎨 Color-optimized for common terminals (iTerm2, Apple Terminal, GNOME, Konsole, tmux/screen)

## Quick Start

```bash
# 1. Clone the repository
git clone https://github.com/BadRat-in/zsh-modern-theme.git $HOME/.zsh/zsh-modern-theme

# 2. Add to your ~/.zshrc
echo 'source $HOME/.zsh/zsh-modern-theme/zsh-modern-theme.zsh' >> ~/.zshrc

# 3. Reload your shell
source ~/.zshrc
```

That's it! The theme will automatically create a config file at `~/.config/zsh-modern-theme/.config.json` with default settings.

## Installation

### Manual Installation

1. Clone the repository:

```bash
git clone https://github.com/BadRat-in/zsh-modern-theme.git $HOME/.zsh/zsh-modern-theme
```

2. Source it in your `~/.zshrc`:

```bash
source $HOME/.zsh/zsh-modern-theme/modern-theme.zsh
```

3. Reload ZSH:

```bash
source ~/.zshrc
```

## Customization

You can customize the theme through configuration files and by overriding variables in your `~/.zshrc`.

### Configuration File

The theme stores its configuration in `~/.config/zsh-modern-theme/.config.json`. The configuration file is **automatically created with default settings** when you first load the theme.

**Configuration file location:** `~/.config/zsh-modern-theme/.config.json`

#### How Configuration Works

1. **First Time Users**: When you first load the theme, it automatically creates the config directory and file with sensible defaults
2. **If Deleted**: If you delete the config file, it will be regenerated with defaults the next time you reload your shell
3. **Custom Settings**: Any changes you make to the config file persist across shell sessions

#### Default Configuration

Here's what the default configuration looks like:

```json
{
  "_comment": "ZSH Modern Theme Configuration",
  "_description": "This file is automatically generated with default settings. Edit values to customize your prompt.",

  "duration_format": "auto",
  "_duration_format_options": {
    "auto": "Automatically formats based on duration (< 60s shows seconds, >= 60s shows m:s or h:m:s)",
    "seconds": "Always show in seconds only (e.g., 83s)",
    "minutes-seconds": "Always show in minutes:seconds format (e.g., 1:23)"
  },

  "git": {
    "clean_symbol": "✓",
    "dirty_symbol": "✗",
    "show_status": true,
    "_symbols_info": "Use Unicode symbols or ASCII alternatives (e.g., '+', 'x', '*')"
  },

  "virtualenv": {
    "show": true,
    "_info": "Show Python virtual environment name in prompt"
  },

  "time": {
    "show": true,
    "show_command_duration": true,
    "timer_icon": "⌛",
    "_timer_icon_options": "Examples: '⌛', '⏱️', '⏲️', '[t]', '(s)'"
  }
}
```

**Note:** Fields starting with `_` are comments for documentation and are ignored by the parser.

---

#### Configuration Options

##### 1. Duration Format

Control how command execution time is displayed:

```json
"duration_format": "auto"
```

**Available options:**

- **`"auto"`** (default) - Automatically formats based on duration:
  - Less than 60 seconds: Shows as `25s`
  - 60-3599 seconds: Shows as `2m 35s`
  - 3600+ seconds: Shows as `1h 15m 30s`

- **`"seconds"`** - Always displays in seconds only:
  - Example: `83s` (even for durations over 1 minute)
  - Useful for precise timing and scripting

- **`"minutes-seconds"`** - Always displays in `MM:SS` format:
  - Example: `0:45` for 45 seconds, `1:23` for 83 seconds
  - More user-friendly for longer commands
  - Automatically zero-pads seconds (e.g., `2:05`)

📖 **[See detailed duration format examples →](docs/DURATION_FORMAT_EXAMPLES.md)**

---

##### 2. Git Configuration

Customize git status display:

```json
"git": {
  "clean_symbol": "✓",
  "dirty_symbol": "✗",
  "show_status": true
}
```

**Options:**

- **`clean_symbol`**: Symbol shown when git repo is clean (default: `"✓"`)
  - Examples: `"✓"`, `"✔"`, `"+"`, `"ok"`, `"clean"`

- **`dirty_symbol`**: Symbol shown when git repo has changes (default: `"✗"`)
  - Examples: `"✗"`, `"✘"`, `"x"`, `"*"`, `"dirty"`

- **`show_status`**: Show/hide git status indicator (default: `true`)
  - Set to `false` to hide the clean/dirty symbol (only shows branch name)

**Example - ASCII symbols:**
```json
"git": {
  "clean_symbol": "+",
  "dirty_symbol": "x",
  "show_status": true
}
```

---

##### 3. Virtual Environment

Control Python virtualenv display:

```json
"virtualenv": {
  "show": true
}
```

**Options:**

- **`show`**: Show/hide virtualenv in prompt (default: `true`)
  - Set to `false` to hide `env:(venv_name)` from prompt

---

##### 4. Time Display

Configure time and duration display:

```json
"time": {
  "show": true,
  "show_command_duration": true,
  "timer_icon": "⌛"
}
```

**Options:**

- **`show`**: Show/hide current time (default: `true`)
  - Set to `false` to hide `HH:MM:SS` from prompt

- **`show_command_duration`**: Show/hide command execution duration (default: `true`)
  - Set to `false` to hide duration timer

- **`timer_icon`**: Icon displayed before duration (default: `"⌛"` or `"[s]"` for non-Unicode terminals)
  - Unicode examples: `"⌛"`, `"⏱️"`, `"⏲️"`, `"⏰"`, `"🕐"`
  - ASCII examples: `"[t]"`, `"(s)"`, `"[s]"`, `"T:"`

**Example - Minimal time display:**
```json
"time": {
  "show": false,
  "show_command_duration": true,
  "timer_icon": "[s]"
}
```
This shows only command duration without current time.

---

#### Example Configurations

**Minimal prompt (no time info):**
```json
{
  "duration_format": "auto",
  "git": {
    "clean_symbol": "✓",
    "dirty_symbol": "✗",
    "show_status": true
  },
  "virtualenv": {
    "show": true
  },
  "time": {
    "show": false,
    "show_command_duration": false,
    "timer_icon": "⌛"
  }
}
```

**ASCII-only symbols:**
```json
{
  "duration_format": "seconds",
  "git": {
    "clean_symbol": "+",
    "dirty_symbol": "x",
    "show_status": true
  },
  "virtualenv": {
    "show": true
  },
  "time": {
    "show": true,
    "show_command_duration": true,
    "timer_icon": "[s]"
  }
}
```

**Focus on command duration:**
```json
{
  "duration_format": "minutes-seconds",
  "git": {
    "clean_symbol": "✓",
    "dirty_symbol": "✗",
    "show_status": false
  },
  "virtualenv": {
    "show": false
  },
  "time": {
    "show": false,
    "show_command_duration": true,
    "timer_icon": "⏱️"
  }
}
```

---

#### Applying Configuration Changes

After editing the configuration file, reload your shell:

```bash
source ~/.zshrc
```

Or simply start a new terminal session.

### Colors

The theme auto-selects colors, but you can override:

```zsh
# Dark theme
typeset -g PROMPT_COLOR=$'%F{033}'    # Bright blue
typeset -g USER_COLOR=$'%F{226}'      # Bright yellow

# Light theme
typeset -g PROMPT_COLOR=$'%F{033}'    # Dark blue
typeset -g USER_COLOR=$'%F{094}'      # Dark gold
```

You can also redefine the **rainbow path colors**:

```zsh
typeset -g RAINBOW_COLORS=(
  $'%F{208}'  # orange
  $'%F{220}'  # yellow
  $'%F{082}'  # green
  $'%F{039}'  # blue
  $'%F{171}'  # purple
  $'%F{033}'  # deep blue
)
```

### Git Symbols

```zsh
typeset -g GIT_CLEAN_SYMBOL='✓'
typeset -g GIT_DIRTY_SYMBOL='✗'
typeset -g GIT_SUFFIX=''   # optional suffix after branch name
```

## FAQ

### What happens on first install?

The theme automatically creates a configuration file at `~/.config/zsh-modern-theme/.config.json` with default settings. No manual setup required!

### What if I delete the config file?

No problem! The theme will automatically regenerate it with default settings the next time you reload your shell. Your prompt will continue working seamlessly.

### Can I use ASCII symbols instead of Unicode?

Yes! Edit your config file and change symbols to ASCII alternatives:

```json
{
  "git": {
    "clean_symbol": "+",
    "dirty_symbol": "x"
  },
  "time": {
    "timer_icon": "[s]"
  }
}
```

### How do I hide certain elements?

Set the corresponding `show` option to `false` in your config file:

```json
{
  "virtualenv": { "show": false },
  "time": { "show": false }
}
```

### Where is the config file located?

`~/.config/zsh-modern-theme/.config.json`

### Does it work with tmux/screen?

Yes! The theme includes special detection for terminal multiplexers and adapts accordingly.

### What terminals are supported?

The theme works with all modern terminals and has been tested on:
- iTerm2 (macOS)
- Apple Terminal (macOS)
- GNOME Terminal (Linux)
- Konsole (Linux)
- Alacritty
- Kitty
- tmux/screen

### How do I reload my configuration?

After editing the config file, simply reload your shell:

```bash
source ~/.zshrc
```

Or start a new terminal session.

## Contributing

Contributions welcome! PRs and issues encouraged.

See [CONTRIBUTING.md](docs/CONTRIBUTING.md) for guidelines.

## License

MIT License – see [LICENSE](LICENSE).

## Author

**Ravindra Singh**
GitHub: [@BadRat-in](https://github.com/BadRat-in)

## Acknowledgments

- Inspired by various ZSH themes in the community
- Thanks to the Oh My Zsh project

## Additional Resources

- 📖 [Detailed Duration Format Examples](docs/DURATION_FORMAT_EXAMPLES.md) - Comprehensive examples of all duration formats
- 📖 [Contributing Guide](docs/CONTRIBUTING.md) - Guidelines for contributing to the project
- 📖 [Project Structure](docs/PROJECT_STRUCTURE.md) - Complete project organization and file descriptions
- 🧪 [Configuration Test Suite](test_configuration.zsh) - Test script to verify configuration loading
- 🧪 [Duration Format Tests](test_duration_format.zsh) - Test script for duration formatting