MHPATH(1)

✨ NAME ✨

mhpath — the little bestie that prints out full pathnames of nmh messages and folders. That's it. That's the whole job. And she does it flawlessly. 💅

She's part of the nmh family, version 1.8, and she lives in the General Commands Manual, section 1. Slay.

---

🌸 SYNOPSIS 🌸

mhpath [-help] [-version] [+folder] [msgs]

🦋 DESCRIPTION 🦋

Okay so here's the vibe: mhpath takes your message list msgs, expands it, sorts it, and then writes the full pathnames of those messages to standard output — each one on its own line, separated by newlines. Clean. Tidy. Iconic.

If you don't give her any msgs at all? She outputs the current mail folder's pathname instead. And if the only argument you pass is +? She prints your nmh “Path” — which, lowkey, is super useful in shell scripts. 🫶

---

🎀 the part where she's different from every other nmh command

Here's the thing bestie — unlike the other nmh commands, a message argument to mhpath may often be intended for writing. And because of that:

1. The name “new” has been added to mhpath's list of reserved message names. The others are “first”, “last”, “prev”, “next”, “cur”, and “all”. The new message is equivalent to the message after the last message in a folder — and equivalent to 1 in a folder that has no messages. ⚠️ The new message may not be used as part of a message range. (Not negotiable, sorry.)
2. Within a message list, the following designations may refer to messages that do not exist: a single numeric message name, the single message name cur, and (obviously) the single message name new. Every other message designation must refer to at least one existing message, if the folder contains messages. Periodt.
3. An empty folder is not, in itself, an error. She's not mad. She's just chill like that. 😌

---

💀 the range rules (pay attention, this is the plot)

• A message number less than that of the smallest existing message in a folder is treated as if the message already exists. (Delulu? No. Intentional.)
• A message number greater than that of the highest existing message in a folder causes an “out of range” error message to be displayed. 🚨
• But if it's part of a range designation that contains messages that do exist, then message numbers less than the smallest — or greater than the highest — existing message in a folder are ignored. Ignored! She's unbothered.

---

🌈 EXAMPLES 🌈 (the main character montage)

So the current folder is foo, it contains messages 3 5 6, and Cur is 4. Watch her work:

$ mhpath
/r/phyl/Mail/foo

$ mhpath all
/r/phyl/Mail/foo/3
/r/phyl/Mail/foo/5
/r/phyl/Mail/foo/6

$ mhpath 2001
mhpath: message 2001 out of range 1-6

$ mhpath 1-2001
/r/phyl/Mail/foo/3
/r/phyl/Mail/foo/5
/r/phyl/Mail/foo/6

$ mhpath new
/r/phyl/Mail/foo/7

$ mhpath last new
/r/phyl/Mail/foo/6
/r/phyl/Mail/foo/7

$ mhpath last-new
mhpath: bad message list last-new

$ mhpath cur
/r/phyl/Mail/foo/4

$ mhpath 1-2
mhpath: no messages in range 1-2

$ mhpath first:2
/r/phyl/Mail/foo/3
/r/phyl/Mail/foo/5

$ mhpath 1 2
/r/phyl/Mail/foo/1
/r/phyl/Mail/foo/2

See how mhpath 1-2 said no messages in range but mhpath 1 2 happily printed /r/phyl/Mail/foo/1 and /r/phyl/Mail/foo/2? Yeah. That's the range rule doing its thing. 🧚

---

🌟 backquoted operations 🌟

mhpath is also that girl inside backquotes:

$ cd `mhpath +inbox`

$ echo `mhpath +`
/r/phyl/Mail

---

⚠️ the cautionary tale (do NOT skip this one)

Because mhpath expands and sorts [msgs], this command:

mv `mhpath 501 500`

will not move 501 to 500. Quite the reverse, actually. 😭 The sorting gets you. But:

mv `mhpath 501` `mhpath 500`

will do the trick. Two separate calls, two separate sorts, no chaos. You're welcome. 💖

---

🔥 one more error note

Out-of-range message 0 produces a different error message than large out-of-range message numbers do. But here's what matters: both cause mhpath to exit with non-zero status. So if you're scripting, check that exit code, bestie. No cap.

---

💜 FILES 💜

• $HOME/.mh_profile — The user profile

🍓 PROFILE COMPONENTS 🍓

• Path: — To determine the user's nmh directory
• Current-Folder: — To find the default current folder

👑 SEE ALSO 👑

• folder(1)

⭐ DEFAULTS ⭐

• +folder defaults to the current folder
• msgs defaults to none

🙈 CONTEXT 🙈

None. (She keeps it simple. No state, no drama.)

---

And that's the whole page, gorgeous — brought to you by nmh-1.8, dated 2012-02-18. Go forth and print some pathnames. 💅✨