cow-shell(1)

💖 cow-shell(1) 💖

okay bestie, so this is a page from the cowdancer manual and it's literally about cow-shell, and I am so ready to tell you about it. buckle up 🎀

---

✨ NAME ✨

cow-shell — start a copy-on-write session and invoke a shell, periodt. 💅

---

🌸 SYNOPSIS 🌸

cow-shell [commandline]

that's it. that's the whole vibe. 🦋

---

💫 DESCRIPTION 💫

so cow-shell runs whatever command you hand it, using cowdancer. and if you give it no command-line option at all? it just drops you into a shell. no big deal, iconic behavior. 👑

here's the tea: once you're inside the cowdancer session, the files under your current directory get protected in a very specific way — if you do a write operation to an i-node that already existed back when you ran cow-shell, that i-node does NOT get modified. she's protected. she's safe. she's not taking that energy today. 😌

ngl this is super useful for managing hard-linked source-trees and scratch-filesystems. that's the whole point, iykyk. 🧚

---

🔥 EXAMPLES 🔥

• cp -al cowdancer/ cowdancer.new && cd cowdancer.new && cow-shell — make a hardlinked tree, then cd into the freshly created tree. after you invoke cow-shell inside that tree, any write operation against a file that's hardlinked with the original tree gets copied to a new file before the write. the original tree is untouched, as she should be. 💅
• cp -al cowdancer/ cowdancer.new && cd cowdancer.new && cow-shell debuild — this one tries to run dpkg-buildpackage on the new tree, specifically so the original tree doesn't get damaged. queen behavior, protecting the original. 👑

heads up bestie!! you need to configure debuild to ignore .ilist files — do it through the -i or -I option. don't skip this one fr fr. 😭

---

🎀 FILES 🎀

• .ilist — generated dynamically in the current directory. this file holds the list of i-node numbers that should be protected from write operations. she's the VIP list. 💖
• /usr/lib/cowdancer/libcowdancer.so — the shared library used internally that overrides some functions that could potentially write to files. this library is literally the COW feature, and it gets preloaded with LD_PRELOAD. main character library energy, no cap. ⭐
• /bin/cp — used for copying. requires the GNU option -a to be functional. non-negotiable. 🌈

---

🦋 ENVIRONMENT 🦋

• COWDANCER_ILISTFILE — the path to the current .ilist file.
• COWDANCER_IGNORE — used internally to work around infinite loops. it will be unset.
• LD_PRELOAD — utilized to preload libcowdancer.so.
• COWDANCER_DEBUG — debugging option. enables debug messages. cowdancer will give verbose debug messages on standard error output.
• COWDANCER_SO — debugging option. specifies a different path for libcowdancer.so.
• COWDANCER_REUSE=yes — enables reuse of the cowdancer .ilist file found for consecutive runs of cow-shell.

---

💜 RETURN VALUE 💜

the functions that get overridden with cowdancer will give an errno value of ENOMEM when there's a problem.

and before you panic — the system isn't actually out of memory, bestie. 😭 this error code was chosen on purpose because this error is usually handled gracefully by applications. it's giving strategic drama. 💀

---

🙈 RESTRICTIONS 🙈

okay this is the part where we get real. read it. love it. respect it.

• can only support directories that are scanned by the cow-shell command.
• the operation is not semantically correct when files are originally hardlinked — hardlinks are always broken.
• does not support anything when the LD_PRELOAD trick doesn't work.
• does not work unless hardlinks are supported on the filesystem.
• not very user-friendly. (she said it, not me 💀)
• leaves the .ilist file around. yeah. she does that. 🙈

---

👑 AUTHOR 👑

Junichi Uekawa (dancer@debian.org)

the upstream page is available at http://www.netfort.gr.jp/~dancer/software/cowdancer.html — go show some love. 🫶

---

🌟 SEE ALSO 🌟

• cowdancer-ilistcreate (1)

---

and that's the whole page bestie!! this one's from the cowdancer manual, dated 2006 Jan 25. yes, she's vintage. yes, she still slays. mwah 💖💅✨