Skip to content

README.org

Latest commit

 

History

History
264 lines (183 loc) · 6.41 KB

README.org

File metadata and controls

264 lines (183 loc) · 6.41 KB
Raw

eshell-p10k

.github/preview.png

eshell-p10k is a modular, extensible prompt framework for eshell inspired by powerlevel10k.

Features

  • Highly customizable powerline-style prompts
  • Pre-built segments: OS/distro, directory, git status, prompt counter
  • Simple API for creating custom segments

Install

Dependencies

  • Emacs 27.1+
  • nerd-icons for default config
  • A Nerd Font installed and configured in your terminal

Manual Installation

Add to your load path:

(add-to-list 'load-path "/path/to/eshell-p10k")

The default prompt will be autoloaded when you use it.

Quick Start

Basic Usage

Use the default prompt configuration (automatically loads on first use):

(setq eshell-prompt-function #'eshell-p10k-default-prompt
      eshell-prompt-regexp eshell-p10k-prompt-regex)

That’s it! The default configuration will be loaded automatically when eshell starts.

The default prompt includes:

  • OS/distribution icon
  • Current directory
  • Git branch and status (when in a repo)
  • Prompt counter

Customization

Powerline Characters

Customize the powerline separators and terminators:

(setq eshell-p10k-separator "\xe0bc"        ; Separator between segments
      eshell-p10k-start-terminator "\xe0b2" ; Start of each segment
      eshell-p10k-end-terminator "\xe0b0")  ; End of prompt

Prompt Structure

Customize the prompt frame:

(setq eshell-p10k-header-string "\n┌─"  ; Prefix before segments
      eshell-p10k-prompt-string "└─> ") ; Input prompt

Creating Custom Segments

Basic Segment

The eshell-p10k-def-segment macro creates a new segment:

(eshell-p10k-def-segment segment-name
  icon        ; Icon to display (or nil)
  form        ; Expression to evaluate
  face)       ; Face to apply

Example: Time Segment

(defface my-time-face
  '((t (:background "purple" :foreground "white")))
  "Face for time segment.")

(eshell-p10k-def-segment time
  ""
  (format-time-string "%H:%M:%S")
  'my-time-face)

Example: Hostname Segment

(defface my-hostname-face
  '((t (:background "orange" :foreground "black")))
  "Face for hostname segment.")

(eshell-p10k-def-segment hostname
  ""
  (system-name)
  'my-hostname-face)

Example: Conditional Segment

Segments that return nil won’t be displayed:

(eshell-p10k-def-segment battery
  ""
  (when (and (featurep 'battery)
             battery-status-function)
    (battery-format "%p%%" (funcall battery-status-function)))
  'my-battery-face)

Creating Custom Prompts

Simple Custom Prompt

Compose your own prompt from segments:

(defun my-custom-prompt ()
  "My custom prompt with time and hostname."
  (eshell-p10k-def-prompt '(hostname dir git time)))

(setq eshell-prompt-function #'my-custom-prompt)

Minimal Prompt

Use only the segments you need:

(defun my-minimal-prompt ()
  "Minimal prompt with directory and git."
  (eshell-p10k-def-prompt '(dir git)))

(setq eshell-prompt-function #'my-minimal-prompt)

Framework-Only Usage

Use only the core framework without default segments (manual require needed):

(require 'eshell-p10k)  ; Core framework only

;; Define your own segments
(eshell-p10k-def-segment my-segment ...)

;; Create your prompt
(defun my-prompt ()
  (eshell-p10k-def-prompt '(my-segment)))

(setq eshell-prompt-function #'my-prompt)

Default Segments

distro

Displays an icon for your OS/distribution:

  • Automatically detects Linux distros from /etc/os-release
  • Supports: Arch, Debian, Ubuntu, Fedora, NixOS, and more
  • Falls back to generic icons for unknown systems

dir

Shows current directory:

  • Uses abbreviate-file-name to shorten paths
  • Replaces home directory with ~

git

Git repository information:

  • Shows current branch name
  • Displays file status counts (e.g., “M 2”, “A 1”)
  • Background color indicates clean (green) or dirty (red) state
  • Only appears when in a git repository

prompt-num

Command counter:

  • Increments with each command
  • Resets when eshell exits
  • Useful for command history navigation

Advanced Examples

Multi-line with User Info

(eshell-p10k-def-segment user
  ""
  (user-login-name)
  'eshell-p10k-distro-face)

(defun my-detailed-prompt ()
  "Multi-line prompt with user info."
  (eshell-p10k-def-prompt '(user hostname dir git prompt-num)))

(setq eshell-prompt-function #'my-detailed-prompt)

Conditional Git Detail

(defcustom my-git-detail-threshold 50
  "Show detailed git status only if repo has fewer than this many files."
  :type 'integer)

(eshell-p10k-def-segment git-smart
  ""
  (when (eshell-p10k--git-repo-p)
    (let ((branch (eshell-p10k--git-branch)))
      (if (< (length (eshell-p10k--git-status-counts)) my-git-detail-threshold)
          (eshell-p10k--git-status)
        branch)))
  (if (eshell-p10k--git-clean-p)
      'eshell-p10k-git-clean-face
    'eshell-p10k-git-dirty-face))

Troubleshooting

Icons Not Displaying

  1. Ensure you have a Nerd Font installed
  2. Run M-x nerd-icons-install-fonts
  3. Configure your terminal to use the Nerd Font

Prompt Not Updating

Make sure you’ve set both variables:

(setq eshell-prompt-function #'eshell-p10k-default-prompt
      eshell-prompt-regexp eshell-p10k-prompt-regex)

Git Segment Performance

For large repositories, git operations may slow down prompt rendering. Consider:

  • Disabling the git segment: (eshell-p10k-def-prompt '(distro dir prompt-num))
  • Using a simpler git segment without status counts

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests on GitHub.

Credit