ondir(1)

🎀 NAME 🎀

okay bestie, welcome to ondir(1), a Shell utility that ✨automatically executes scripts when you traverse directories at the command line✨. yes she does that. she's iconic.

---

🦋 SYNPOSIS 🦋

ondir <old-directory> [<new-directory>]

---

💖 DESCRIPTION 💖

NOTE: the 0.2.x series has been completely rewritten in C. also, and this is the part that matters, the configuration file format is substantially different. so don't come at her with your old 0.1.x config and expect it to hit, because it will not.

okay so what does ondir actually do, bestie? she's a program that executes a script when entering or leaving a directory. but that's not even the best part — she also executes all the scripts in the intermediate directories between the two. like, the whole journey, not just the destination. main character behavior fr.

for example, when you change from /opt/music to /home, the leave scripts for /opt/music and /opt are executed, and then the enter script for /home is executed. see? she walks you out of every room you were in before she walks you into the new one. etiquette. 💅

the scripts are defined in either the system-wide rc file (/etc/ondirrc) or per user rc files (~/.ondirrc).

the way ondir works is by using auxiliary scripts that override shell builtins (cd, pushd and popd in BASH) so that ondir gets run whenever a user changes directory. these scripts are included in the section SCRIPTS, below. 👇

the scripts are available in the source tarball and are called scripts.sh, scripts.tcsh for Bourne shell variants and TCSH, respectively.

---

✨ OPTIONS ✨

• <old-directory> — the last directory you were in, after having changed to the new directory. yeah, she wants to know where you came from. she's nosy like that 🫶
• [<new-directory>] — the current directory. this one's optional, but she's lowkey useful when you're traversing symbolically linked paths, because she'll use the logical path rather than the physical path. if you leave her out, ondir uses getcwd(). no biggie either way 💜

---

🌸 CONFIGURATION 🌸

the configuration files /etc/ondirrc and ~/.ondirrc are in the form:

# Comment
[final] enter <path>[:<path>[:...]]
     <shell script body>
[final] leave <path>[:<path>[:...]]
     <shell script body>

any line with leading whitespace is assumed to belong to the last valid enter or leave section. so mind your indentation, bestie, she's reading into it 😭

final indicates that the section will be the last one executed for the matching directory. directories further down the hierarchy will still be matched though. she's not ghosting them, she's just giving them the closing slot.

<path> is the path to match. regular expression support has been included since version 0.2.1, thanks to Arvind (?). a path must match completely to be considered a match. and because : is the path delimiter, it can not be used in any regular expressions. that's the rules, babe. no exceptions. 🚫

Arvind also re-added (from version 0.1.x) support for $ONDIRWD expansion. this environment variable will contain the directory currently being traversed. obsessed with her honestly.

a perfect example of the usefulness of this program is a user's public_html directory. 👑

I personally set my default umask to 077, but when editing in my public_html directory I want my umask to be 022. To do this automatically, I would have add the following to my ~/.ondirrc:

~/.ondirrc
enter /home/athomas/public_html
     umask 022
leave /home/athomas/public_html
     umask 077

another good example is if you have a bin directory in a project, but don't want to add it permanently to your PATH. the following ondir scripts take care of that:

~/.ondirrc
enter /home/athomas/projects/myproject
     PATH=$PATH:$CWD/bin
leave /home/athomas/projects/myproject
     PATH=`echo $PATH | sed -e "s,:$CWD/bin,,g"`

---

🧚 SCRIPTS 🧚

on Debian systems the integration scripts are installed in /usr/share/ondir/integration to simplify integration into one's own shell. to enable ondir, one needs to include these files in the shell's startup. one time setup, forever slay. 💅

when using bash, add the following to your ~/.bashrc:

source /usr/share/ondir/integration/bash

when using zsh, add the following to your ~/.zshrc:

source /usr/share/ondir/integration/zsh

when using fish, run the following commands:

mkdir -p ~/.config/fish/conf.d
ln -s /usr/share/ondir/integration/fish \
      ~/.config/fish/conf.d/ondir_prompt_hook.fish

---

👑 AUTHORS 👑

Alec Thomas <alec@swapoff.org> — the one and only. thank you for your service 🫡💖

---

🌈 SEE ALSO 🌈

devtodo(1) <http://swapoff.org/DevTodo> — go check her out too, she's part of the family.

---

💀 NOTES 💀

ondir also has the ability to execute scripts in the directories being traversed. these scripts are named .onenter and .onleave. this ability is disabled by default, but can be enabled by editing conf.h and uncommenting:

#define USE_ONENTERLEAVE

this functionality is disabled in the Debian package for security reasons. so like... don't go uncommenting things and then being surprised, bestie. 🔥

---

and that's the whole page, fr fr. this was ondir(1), version 0.2.3, brought to you by Alec Thomas — written down in the manual, and now lovingly retold to you. go change some directories and let her cook 🦋✨🎀