hellishrc.example

# ═══════════════════════════════════════════════════════════════════════
#  ~/.hellishrc — hellish interactive configuration
#  Copy this file to ~/.hellishrc; it is sourced by every interactive
#  hellish (never by scripts, -c, or piped input — tests stay clean).
# ═══════════════════════════════════════════════════════════════════════

# ── 0. COMING FROM ZSH? ───────────────────────────────────────────────
# This file is read with bash rules. A zsh config pasted in as-is breaks
# on the very first zsh idiom -- `precmd() { vcs_info }` closes its group
# with a bare `}` in zsh, but in bash that `}` is an ARGUMENT and the
# rest of the file is swallowed ("syntax error: unexpected end of file",
# issue #112). Two ways to keep zsh syntax, both without a rewrite:
#
#   emulate zsh          as the FIRST LINE of this file: everything after
#                        it is read with zsh rules (set -o zsh works too)
#   ~/.config/hellish/rc.d/50-mine.zsh
#                        a module with a .zsh extension is read with zsh
#                        rules automatically -- no marker needed. The
#                        installer offers to write one that loads your
#                        whole ~/.zshrc (rc.d/90-zshrc.zsh).
#
# vcs_info, zstyle ':vcs_info:*' (formats, stagedstr, unstagedstr,
# check-for-changes), PROMPT, RPROMPT, precmd/preexec, autoload, colors:
# all of that works, and PROMPT is expanded in zsh's own order (parameters
# first, then %F{...} and friends over the result).

# ── 1. PROMPT ──────────────────────────────────────────────────────────
# Unconfigured, hellish shows zsh's own default -- "hostname% " -- plus
# the ⬆ badge when an update is pending. The rich two-row theme is one
# command away (`prompt` lists them; PS1='\B' is the same theme by name).
# Setting PS1 replaces the prompt entirely. Bash escape set:
#   \u user   \h host   \H host.fqdn   \w cwd(~)   \W cwd basename
#   \$ $/#    \n newline   \t HH:MM:SS   \T 12h   \@ am/pm   \d date
#   \j job count   \l tty   \! history no.   \# command no.
#   \s shell  \v \V version   \e ESC   \r CR   \[ \] readline width guards
#   \D{strftime-format} custom clock
#
# PS1 is BILINGUAL: zsh's % syntax works right here too, alongside the
# backslash set -- %n %m %~ %d %c, %F{color}/%f (names, 0-255, #rrggbb),
# %B %U %S, %K, %{...%}, %? %j %h %L %#, the %T/%t/%*/%D clocks,
# %(x.true.false) conditionals, %n<...< truncation -- all verified
# byte-for-byte against zsh 5.9 (tests/zsh_prompt_parity_test.py).
#     PS1='%F{cyan}%~%f %(?.%F{green}.%F{red})%#%f '
# Your old percents are safe: an unknown or unclosed % sequence stays on
# screen literally ('100% ', '%> '), and the strftime percents inside
# $(...) or \D{...} are never touched. PROMPT is the same language with
# EXACT zsh semantics (unknown escapes vanish, as zsh does); it wins over
# PS1 when both are set, and `set -o zsh` gives PS1 those exact
# semantics too, since in zsh PS1 and PROMPT are one parameter.
# hellish extensions — all SELF-SPACING (invisible until relevant):
#   \g  git branch of the cwd (+ * when dirty), empty outside a repo
#   \S  " ✘N" after a failing command, empty after success
#   \p  " took N.Ns" once a command ran 2s or longer
#   \J  " ⚙N" while background jobs exist
#   \U  " ⬆X.Y.Z" while a newer release is waiting, empty otherwise. The
#       "update available" notice is said ONCE and then never again; this
#       is the quiet marker that stays until you actually update. The
#       built-in prompt shows it already -- add \U to a custom PS1 to keep
#       it. Silenced by HELLISH_NO_UPDATE_CHECK like the rest.
#   \A  an ANIMATED glyph (see HELLISH_ANIM below) — OPT-IN, off by
#       default. (Shadows bash's \A 24h-clock escape; use \t for time.)
# Live $VAR / ${VAR} expansion happens at every render, and so does $? and
# the other single-character specials ($$, $!, $#, $1...). QUOTE PS1 WITH
# SINGLE QUOTES if you use them: in double quotes the shell expands $? once,
# when you ASSIGN it, and bakes that one value in forever -- which looks
# exactly like a prompt that cannot see your exit status (issue #69).
#
#     PS1='[$?] \$ '     # re-read every prompt   <- what you want
#     PS1="[$?] \$ "     # frozen at assignment
#
# \S is usually the nicer answer than $? anyway: it shows " ✘N" only after a
# failure and stays invisible when everything is fine.

# ── ANIMATION: OFF BY DEFAULT, AND THAT IS DELIBERATE ──────────────────
# A live style makes \A repaint the prompt rows in place ~10x/second
# while the shell sits idle. That repaint is the one part of the prompt
# that writes to your terminal when you are NOT typing, and it has been
# reported to corrupt the prompt on some terminals — an escape sequence
# arriving without its introducer prints its body as text
# (`8;2;90;96;106m`), or a multibyte glyph gets cut and shows as U+FFFD.
# It is not reproducible on demand, so it is shipped OFF rather than
# shipped broken. Everything else in this file works exactly the same
# with animation off; \A simply renders nothing.
#
# Styles, if you want to opt in anyway:
#   spinner  braille spinner in blue        pulse  a ✦ breathing magenta
#   ember    a ▲ flickering through fire    off    hide \A (default)
HELLISH_ANIM=off

# Theme: "pure" (default) — a blank line for breathing room, then one
# calm info line (bold blue path, grey branch, red failure badge, amber
# duration, blue jobs), then a lone magenta arrow on its own line. Your
# commands always start at the same column, and nothing appears unless
# it carries information.
#
#     ~/Documents/hellish feat/rc-theming* ✘1 took 3.2s ⚙1
#     ❯
# The prompt now lives in its own file, not here:
#
#     ~/.config/hellish/rc.d/30-prompt.hsh
#
# That is issue #74 -- "this prompt should exist in configuration so we can
# retouch it and not in binary only". rc.d is loaded BEFORE this file, so
# anything you set here still wins; the split just means the default is
# somewhere obvious and editable instead of compiled in.
#
# Uncomment either of these to override it from here. Note they are the
# richer two-row themes -- the seeded default is deliberately plainer.
#
# Theme: "pure"
# PS1='\n\[\e[1;38;2;122;162;247m\]\w\[\e[0m\] \[\e[38;2;125;133;144m\]\g\[\e[0m\]\[\e[1;38;2;224;108;117m\]\S\[\e[0m\]\[\e[38;2;229;192;123m\]\p\[\e[0m\]\[\e[1;38;2;125;207;255m\]\J\[\e[0m\] \A\n\[\e[1;38;2;198;120;221m\]❯\[\e[0m\] '
# PS2='\[\e[38;2;125;133;144m\]❯\[\e[0m\] '

# Theme: "powerline" — solid colour blocks, from issue #68. Reverse-video
# segments in 24-bit colour, with the git/failure/duration/update badges in
# the last block so it stays quiet until something is worth saying.
# PS1='\[\e[1;38;2;20;20;20;48;2;152;195;121m\] ➜ \[\e[0m\]\[\e[1;38;2;20;20;20;48;2;229;192;123m\] \u@\h \[\e[0m\]\[\e[1;38;2;20;20;20;48;2;224;108;117m\] \w \[\e[0m\]\[\e[1;38;2;20;20;20;48;2;152;195;121m\] \g\S\p\J\U \[\e[0m\] '

# Theme: "ember" — framed two-liner, user shown, same badges.
# PS1='\[\e[38;2;90;96;106m\]╭─\[\e[0m\] \[\e[1;38;2;122;162;247m\]\u\[\e[0m\] \[\e[38;2;108;114;125m\]in\[\e[0m\] \[\e[1;38;2;158;203;255m\]\w\[\e[0m\] \[\e[1;38;2;152;195;121m\]\g\[\e[0m\]\[\e[1;38;2;224;108;117m\]\S\[\e[0m\]\n\[\e[38;2;90;96;106m\]╰─\[\e[0m\] \[\e[1;38;2;152;195;121m\]❯\[\e[0m\] '
# PS2='\[\e[38;2;108;114;125m\]│ \[\e[0m\]'

# Theme: "minimal" — everything on one line, basename only.
# PS1='\[\e[1;38;2;122;162;247m\]\W\[\e[0m\]\[\e[38;2;125;133;144m\] \g\[\e[0m\]\[\e[1;38;2;224;108;117m\]\S\[\e[0m\] \[\e[1;38;2;152;195;121m\]❯\[\e[0m\] '

# Theme: "classic" — bash look, zero color.
# PS1='\u@\h:\w\$ '

# ── 2. LINE EDITING & OPTIONS ─────────────────────────────────────────
# set -o supports: errexit nounset xtrace noglob noclobber allexport
#                  noexec verbose pipefail vi emacs
set -o emacs            # line editing mode (or: set -o vi)
# set -o noclobber      # `>` refuses to overwrite files; force with >|
# set -o pipefail       # a pipeline fails if ANY stage fails

# ── 3. ENVIRONMENT ────────────────────────────────────────────────────
export EDITOR=vim
export PAGER=less
export LESS='-R'        # let pagers pass ANSI colors through

# PATH — this TEMPLATE sets none, and the installer appends exactly one
# block. Both halves matter, and they used to be one over-general rule.
#
# A LOGIN hellish (chsh, or --login) sources /etc/profile — and so the .sh
# snippets in /etc/profile.d, which is where your distro adds things like
# /snap/bin — and then ~/.profile, which on Debian/Ubuntu is what puts
# ~/.local/bin and ~/bin on PATH. All of that runs BEFORE this file. On
# that route the PATH you had under bash carries over whole; there is
# nothing to rebuild, and a prepend here would only duplicate what the
# login chain did a moment earlier. Worse, it read as the pattern you were
# meant to follow, so PATH edits got copy-pasted in over and over (issue
# #51). That is why the template ships none.
#
# `make user-install` is the case that reasoning did NOT cover, and the
# installer now fixes it at the end of this file instead. Hellish is exec'd
# there from an INTERACTIVE rc, so it is not a login shell and reads
# neither /etc/profile nor ~/.profile — and ~/.profile would not have
# helped anyway, because it adds ~/.local/bin only when that directory
# already exists at login and the install is what created it. The shell
# started fine (the hook execs an absolute path) while its own NAME
# resolved nowhere. So user-install appends a marked block for the
# directory it really installed into; it is regenerated on re-install and
# removed by `make user-uninstall`. Leave the markers alone and it will
# never fight your edits.
#
# You need a line of your own here only for a directory neither of those
# covers, or one you want under hellish and nowhere else. If you add one,
# keep the case guard: this file is re-sourced by every nested interactive
# hellish, and an unguarded prepend stacks a fresh copy each time until
# PATH is mostly duplicates.
#
# case ":$PATH:" in
#	*":$HOME/.cargo/bin:"*) ;;
#	*) export PATH="$HOME/.cargo/bin:$PATH" ;;
# esac

# ── 4. ALIASES ────────────────────────────────────────────────────────
alias ls='ls --color=auto'
alias ll='ls -lh --color=auto'
alias la='ls -lha --color=auto'
alias grep='grep --color=auto'
alias ..='cd ..'
alias ...='cd ../..'
alias g='git'
alias gs='git status --short'
alias gl='git log --oneline -15'
alias gd='git diff'

# ── 5. FUNCTIONS ──────────────────────────────────────────────────────
# mkcd DIR: create a directory (parents included) and cd into it.
mkcd() { mkdir -p "$1" && cd "$1"; }

# up [N]: climb N directories (default 1).
up() {
	n="${1:-1}"
	while [ "$n" -gt 0 ]; do
		cd ..
		n=$((n - 1))
	done
}

# ── 5b. HOOKS: RUN SOMETHING AROUND EVERY COMMAND ─────────────────────
# Two arrays of FUNCTION NAMES. Everything named in them runs, in order.
#
#   HELLISH_PRECMD_FUNCS    just before each prompt is drawn
#   HELLISH_PREEXEC_FUNCS   just before a typed line runs; $1 is the line
#
# Arrays, and not one string of code, so that two plugins can both attach.
# `trap ... DEBUG` holds exactly one handler: the second thing to install
# one silently removes the first, and neither can tell. Appending a name to
# an array cannot do that.
#
#   note_dir()  { echo "[$PWD]"; }
#   log_cmd()   { printf '%s\t%s\n' "$(date +%s)" "$1" >> ~/.cmdlog; }
#   HELLISH_PRECMD_FUNCS=(note_dir)
#   HELLISH_PREEXEC_FUNCS=(log_cmd)
#
# A plain string works too -- HELLISH_PRECMD_FUNCS='a b' -- for when you are
# adding one name and would rather not think about arrays.
#
# $? is saved and put back around the hooks, so a prompt with a status badge
# still shows YOUR command's result and not the hook's. Interactive shells
# only: scripts and `-c` never run them.

# ── 6. HISTORY ────────────────────────────────────────────────────────
# Kept in ~/.hellish_history. By DEFAULT a multi-line command is stored as
# one joined entry -- `for i in 1 2\ndo\n...` comes back as
# `for i in 1 2; do ...` -- which is what bash does.
#
# If you would rather get the layout back exactly as you typed it,
# newlines and indentation intact, that is one line (see section 7):
#
#   pretty on multiline-history

# ── 7. PRETTY: NAMED PRESETS FOR HOW THE SHELL FEELS ──────────────────
# `pretty` is a curated front-end over the behaviour knobs that change how
# the shell FEELS rather than what it computes. Every feature it names IS
# a `shopt` option underneath -- there is no second set of state, so the
# two can never disagree -- but `pretty` gives them readable names, one
# line of help each, and presets that bundle them.
#
#   pretty list          every feature and mode, with descriptions
#   pretty               what is on right now
#   pretty -p            the same, as lines you can paste back in HERE
#
# That last one is the point: `pretty -p` prints a configuration you can
# copy to another machine, instead of one you have to remember.
#
# Modes are one-shot assignments, so a toggle after a mode wins:
#
#   plain      everything off -- bash-identical behaviour
#   friendly   multiline-history, cd-spell, resize-aware
#   full       every feature
#
# Uncomment whichever line you want. `friendly` is a good starting point,
# and it is the one that gives you multi-line history recall.

# pretty mode friendly

# ... or pick features individually:
# pretty on multiline-history   # recall keeps newlines and indentation
# pretty on cd-spell            # cd fixes a small typo in a directory name
# pretty on auto-cd             # a bare directory name changes to it
# pretty on resize-aware        # track terminal size after every command
# pretty on deep-glob           # ** matches across directory levels
# pretty on extended-glob       # ?() *() +() @() !() pattern operators
# pretty on case-blind-glob     # globs ignore case
# pretty on hidden-glob         # * also matches dot-files

# ── 8. HELLISH DIAGNOSTIC TOGGLES (for the curious) ───────────────────
# HELLISH_ALLOC_STATS=1 hellish script.sh   # live heap bytes at exit
# HELLISH_PROMPT_BENCH=1 hellish            # ns per prompt render
# hellish --debug=lexer --debug=parser --debug=ast  # pipeline views