Home

Awesome

mommy 💝

github latest release mommy is on aur github ci status mommy is licensed under unlicense

<a name="toc"></a>🚚 installation | 📖 usage | 🙋 configuration | 🐚 shell integration | ⚗️ development | 💖 acknowledgements

mommy's here to support you! mommy will compliment you if things go well, and will encourage you if things are not going so well~

mommy is fully customizable, integrates with any shell, works on any system, and most importantly, loves you very much~ ❤️

<img width="450px" src=".github/img/fish.png" alt="a command-line interface showing the text 'it's okay to make mistakes' after the user has failed to enter their password correctly three times in a row" />

🚚 installation<a name="installation"></a> <small><sup>top ▲</sup></small>

mommy works on any system. mommy is tested on ubuntu, debian, archlinux, fedora, nixpkgs, macos, freebsd, netbsd, openbsd, and windows~

don't see your favourite distro or package manager listed? need help? otherwise not satisfied? please open an issue~

👩‍💼 with a package manager

find your operating system and package manager for the right instructions~

<details> <summary>alpine linux</summary> </details> <details> <summary>arch linux</summary> </details> <details> <summary>debian/ubuntu/apt-based</summary> </details> <details> <summary>freebsd</summary> </details> <details> <summary>macos</summary> </details> <details> <summary>netbsd</summary> </details> <details> <summary>nixpkgs/nixos</summary> </details> <details> <summary>openbsd</summary> </details> <details> <summary>red hat/fedora/opensuse/rpm-based</summary> </details> <details> <summary>windows</summary>

for git bash or cygwin, see the instructions for using mommy without a package manager~

</details>

🐐 without a package manager

<details> <summary>build from source and install</summary>

if you want to customise where and how mommy installs, you can just compile her code yourself~

  1. prerequisites

  2. clone repository

    git clone https://github.com/FWDekker/mommy.git
cd mommy

  3. install
    this step builds mommy's files and copies them into your system. the exact paths differ per system, so find the instructions that are right for your system.

    ℹ️ note
    if you want to install mommy only for the current user, add prefix='~/.local/' before install~

    💡 tip
    check the makefile for a list of all prefix variables you can override~

    • debian/ubuntu/apt-based 
      sudo make install/deb
    • freebsd 
      sudo gmake install/freebsd
    • macos 
      sudo gmake install/osxpkg
    • netbsd 
      sudo gmake install/netbsd
    • openbsd 
      sudo gmake install/openbsd
    • windows 
      sudo make install
    • all other unix systems 
      sudo make install

  4. test (optional)
    if you want to make sure installation was successful, you can run tests using shellspec. run the following from inside the cloned mommy repository

    git clone https://github.com/shellspec/shellspec.git
PATH="$(pwd)/shellspec/:$PATH" make system=1 test

    some tests will be skipped, depending on which other programs you have installed~

  5. uninstall (optional)
    if you want to uninstall after running make install, just run the same command as in step 3, except you replace install with uninstall.

    uninstall might not work completely if you installed a different version than the one you're uninstalling. for the best results, run mommy -v, check the version number, run git checkout <the version>, and then perform the uninstallation~

</details> <details> <summary>use without installing</summary>

if you don't want to use a package manager but also don't want to bother with makeing mommy, you can download a universal build of mommy, and play around with that. this will not install any files onto your system. if you're here because you want to install mommy only for a specific user, the "build from source and install" option is probably a better approach, though~

the script below downloads the latest stable release and extracts it for you. if you don't want to use curl, just check the latest release in your browser and download the file ending in +generic.tar.gz manually~

# download latest archive from github release
curl -s https://api.github.com/repos/FWDekker/mommy/releases/latest | grep "browser_download_url.*generic\.tar\.gz" | cut -d : -f 2,3 | tr -d \" | xargs curl -sLOJ
# extract archive to `mommy`
tar -C ./ -xzf mommy-*.tar.gz
# invoke mommy
./mommy/usr/bin/mommy
</details>

🔮 what's next?

check out how to use mommy, read all about ways you can configure mommy, and integrate mommy with your shell~

<img width="450px" src=".github/img/demo.gif" alt="a command-line interface showing the text 'never give up, my love' after running a command that has failed, and showing the text 'mommy knew you could do it' after running a command that has succeeded" />

📖 usage<a name="usage"></a> <small><sup>top ▲</sup></small>

mommy processes (the output status of) a command and compliments you if the command succeeds and encourages you if it fails~

[!TIP] the recommended way of long-term mommy usage is to integrate mommy into your shell, so mommy will run after every command you run~

💃 how to run<a name="how-to-run"></a>

for reference, here's the three main ways to invoke mommy~

formatexamplewhen to use
mommy [command] ...mommy npm testif you want mommy to respond to a single command~
mommy -e [command]mommy -e "ls -l | wc -l"if you want mommy when using | or >, or need mommy in a script~
mommy -s [status]mommy -s $?if you already ran a command and want mommy's help afterwards~

🛸 extra options<a name="extra-options"></a>

additionally, mommy knows a few extra options, which you can use to discover who mommy is and to tell mommy which configuration files she should use~

short optionlong optiondescription
-h--helpopens mommy's manual page~
-v--versiondisplays mommy's version information~
-1writes output to stdout instead of stderr~
-c <file>--config=<file>tells mommy that she should read your config from <file>~
-d <dirs>--global-config-dirs=<dirs>sets global configuration dirs to the colon-separated list in <dirs>~

🙋 configuration<a name="configuration"></a> <small><sup>top ▲</sup></small>

mommy's behavior can be modified using config files. the easiest way to do so is to add your config to the file ~/.config/mommy/config.sh. you can also set up a global config file that is applied to all users, by default in /etc/mommy/config.sh. read more about the way config files are loaded~

mommy supports a lot of different settings. if you want to configure the value of MOMMY_SWEETIE, add the following line to your config file:

MOMMY_SWEETIE="catgirl"

make sure you do not put spaces around the =, and you do put quotes (") around the value~

<details> <summary><a name="config-file-locations"></a>🔍 config file locations</summary>

when mommy runs, she will first load the system-wide global config file. after that, she will read the user-specific local config file, overriding the values from the global file~

</details> <details> <summary><a name="list-of-all-settings"></a>👛 list of all settings</summary>
variabledescriptionlist?default
MOMMY_CAREGIVERwhat mommy calls herselfyesmommy
MOMMY_PRONOUNSmommy's pronouns for herself. should be three words separated by spaces, as in they them their (subject, object, possessive)yesshe her her
MOMMY_SWEETIEwhat mommy calls youyes<username>
MOMMY_PREFIXwhat mommy puts at the start of each sentenceyes<empty>
MOMMY_SUFFIXwhat mommy puts at the end of each sentenceyes~
MOMMY_CAPITALIZE0 to start sentences in lowercase, 1 for uppercase, anything else to change nothingno0
MOMMY_COLORcolor of mommy's text. you can use any xterm color code, or write lolcat to use lolcat (install separately). specify multiple colors separated by / to randomly select one. set to empty string for your terminal's default coloryes005
MOMMY_COMPLIMENTSdefault compliment templatesyes<various>
MOMMY_COMPLIMENTS_EXTRAadditional compliment templates you can specifyyes<empty>
MOMMY_COMPLIMENTS_ENABLED1 to enable compliments, anything else to disableno1
MOMMY_ENCOURAGEMENTSdefault encouragement templatesyes<various>
MOMMY_ENCOURAGEMENTS_EXTRAadditional encouragement templates you can specifyyes<empty>
MOMMY_ENCOURAGEMENTS_ENABLED1 to enable encouragements, anything else to disableno1
MOMMY_FORBIDDEN_WORDSmommy will never give outputs that match forbidden strings. each entry is expressed as an extended regex (see also man grep). to enforce this, mommy will filter out all templates that match at least one regex. as a failsafe, mommy will also check her final output after choosing and filling in the template, and will output nothing if she finds a forbidden string. also, if you want, you can replace literal characters with their octal (not hex!) escape sequences; for example, you can write \0155\0157\0155 instead of momyes<empty>
MOMMY_IGNORED_STATUSESexit codes that mommy should never reply to. set to empty string to ignore nothingyes130
</details> <details> <summary><a name="how-to-configure-lists"></a>🪣 how to configure lists</summary>

some of these settings support lists. mommy chooses a random element from each list each time she is called by you. (except for MOMMY_FORBIDDEN_WORDS and MOMMY_IGNORED_STATUSES, where mommy always considers all elements of the list.) in a list, elements are separated by a newline or by a /. elements that contain whitespace only, and elements that start with a # are ignored~

</details> <details> <summary><a name="how-to-configure-templates"></a>🧬 how to configure templates</summary>

you can add a list of your own compliments to either MOMMY_COMPLIMENTS or MOMMY_COMPLIMENTS_EXTRA. there is a slight difference between the two lists:

and similarly so for encouragements~

inside compliments and encouragements, you can put placeholders that contain the random values that mommy chose. for example, if you add the compliment %%CAREGIVER%% loves you, and have MOMMY_CAREGIVER=your mommy, then mommy outputs your mommy loves you~

variabledescription
%%CAREGIVER%%what mommy calls herself
%%THEY%%mommy's subject pronoun (e.g. they, she, he)
%%THEM%%mommy's object pronoun (e.g. them, her, he)
%%THEIR%%mommy's possessive pronoun (e.g. their, her, he)
%%SWEETIE%%what mommy calls you
%%N%%a newline
%%S%%a forward slash (/)
</details>

🐚 shell integration<a name="shell-integration"></a> <small><sup>top ▲</sup></small>

instead of calling mommy for each command, you can fully integrate mommy with your shell to get mommy's output each time you run any command. here are some examples on how you can do that in various shells. recall that you can add MOMMY_COMPLIMENTS_ENABLED=0 to your mommy config file to disable compliments while keeping encouragements~

this is just a small list of possibilities. if you know of another way to integrate mommy, feel free to contribute them by opening a pull request!

<details> <summary>🪅 bash</summary>

in bash you can set PROMPT_COMMAND to run mommy after each command. just add the following line to ~/.bashrc:

PROMPT_COMMAND="mommy -1 -s \$?; $PROMPT_COMMAND"
<img width="450px" src=".github/img/demo.gif" alt="bash showing the text 'it's okay to make mistakes' after running a command that has failed" /> </details> <details> <summary>🐟 fish</summary>

in fish you can have mommy output a message on the right side of your prompt by creating ~/.config/fish/functions/fish_right_prompt.fish with the following contents:

function fish_right_prompt
    mommy -1 -s $status
end

if you have an oh my fish theme installed, check the docs of your theme to see if there's an easy way to extend the theme's right prompt. if not, you can either overwrite it with the above code, or copy-paste the theme's code into your own config file and then add mommy yourself~

<img width="450px" src=".github/img/fish.png" alt="fish shell showing the text 'it's okay to make mistakes' in the right prompt after running a command that has failed" /> </details> <details> <summary>📈 nushell</summary>

in nushell you can have mommy output a message on the right side of your prompt by adding the following line to your ~/.config/nushell/config.nu file:

$env.PROMPT_COMMAND_RIGHT = {|| mommy -1 -s $env.LAST_EXIT_CODE }
<img width="450px" src=".github/img/nushell.png" alt="nushell showing the text 'just a little further, mommy knows you can do it' in the right prompt after running a command that has failed" /> </details> <details> <summary>🪟 powershell</summary>

the exact instructions depend on how and where you installed mommy~

  1. disable mommy's color output
    mommy's colors don't really work well in powershell, so you'll have to disable them~

    • wsl
      if you want to run mommy through wsl, open wsl and run 
      # run this in wsl
mkdir -p ~/.config/mommy
echo "MOMMY_COLOR=" >> ~/.config/mommy/config.sh
    • git bash
      if you want to run mommy through git bash, run 
      # run this in powershell
[IO.Directory]::CreateDirectory("$HOME/.config/mommy")
[IO.File]::WriteAllLines("$HOME/.config/mommy/config.sh", "MOMMY_COLOR=''")

  2. test prompt
    change powershell's prompt to include mommy's message~

    • wsl
      if you want to run mommy through wsl, run 
      # run this in powershell
function prompt { "$(wsl -e mommy -1 -s $([int][bool]::Parse(!$?)))> " }
    • git bash
      if you want to run mommy through git bash, and you downloaded mommy to C:\Users\username\mommy, run 
      # run this in powershell
function prompt { "$(& "C:\Program Files\Git\bin\sh.exe" "C:/Users/username/mommy" -1 -s $([int][bool]::Parse(!$?)))> " }

  3. save prompt
    now let's make this prompt persistent. in powershell, run notepad $profile to open your powershell settings, and add the function prompt [...] line from above~

    ℹ️ note
    if you get an error that this file does not exist, run new-item -itemtype file -path $profile -force to create it~

    ℹ️ note
    if you get an error that you cannot run local scripts, run Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope LocalMachine as admin, or sign the script~

  4. improve prompt
    the instructions above show the basics of using mommy in powershell. you can make it way cooler using a theme engine like oh-my-posh. for example, you can use background colors or display mommy in the right prompt instead of the left~

</details> <details> <summary>💤 zsh</summary>

depending on where you want mommy's output, the instructions are a bit different. you can either get the output above your prompt, or aligned to the right~

above the prompt
to get mommy's output on a separate line above your prompt, add the following line to ~/.zshrc:

precmd() { mommy -1 -s $? }

to the right of each command
to get mommy's output on the same line as your prompt, aligned to the right, add the following to ~/.zshrc:

set -o PROMPT_SUBST
RPS1='$(mommy -1 -s $?)'  # using single quotes here is required!

and add the following to your mommy config:

MOMMY_COLOR=""
MOMMY_PREFIX="%F{005}/%F{006}"
MOMMY_SUFFIX="~%f"

normally, mommy sets colors using standard ansi color codes, but zsh's support is a bit special, resulting in zsh miscalculating the prompt width, which looks like your prompt is misaligned or shifted. to fix this, you should disable mommy's color feature and manually set colors in the prefix option. to specify colors, use zsh's special syntax, where the numbers correspond to the xterm color codes. finally, the %f in the suffix resets the colors~

<img width="450px" src=".github/img/zsh.png" alt="zsh showing the text 'never give up, my love' in the right prompt after running a command that has failed" /> </details> <details> <summary>🐌 other shells</summary>

as a generic method, in any posix shell (including sh, ash, dash, bash) you can change the prompt itself to contain a message from mommy by setting the $PS1 variable:

PS1="\$(mommy -1 -s \$?)$PS1"

to improve the spacing, set MOMMY_SUFFIX="~ " in mommy's config file.

add the above line to the config file for your shell (e.g. .bashrc for bash) to apply it each time you open the shell. some shells (dash, pdksh) do not have a config file like .bashrc, but you can enable one by adding the following line to ~/.profile:

export ENV="$HOME/.shrc"

note that this will apply to all (non-login) posix shells that you open. after that, add the above-mentioned line that defines PS1 to ~/.shrc. log out and back in, and mommy will appear in your shell~

</details> <details> <summary><a name="renaming-the-mommy-executable"></a>✍️ renaming the mommy executable</summary>

if you use any of the above integrations, you don't have to call mommy directly. if you don't want that, but also don't want to write mommy, this section explains how you can instead write, say, daddy, marija, or sinterklaas~

mommy is installed in slightly different locations on different systems, but you can easily find where mommy is installed with whereis mommy:

$ whereis mommy
mommy: /usr/bin/mommy /usr/share/man/man1/mommy.1.gz

the exact output of whereis differs depending on your system, but in this case you can see that the program is installed in /usr/bin/mommy (and the manual page in /usr/share/man/man1/mommy.1.gz). if whereis mommy doesn't work, mommy is not on your path, but you can still find her with find / -name mommy~

anyway, after finding mommy, you can just symlink using the following commands: (if whereis gave different paths than the ones above, then change these commands accordingly)

sudo ln -fs /usr/bin/mommy /usr/bin/daddy
sudo ln -fs /usr/share/man/man1/mommy.1.gz /usr/share/man/man1/daddy.1.gz

[!IMPORTANT] uninstalling mommy will not remove the manually created symlinks~

</details>

⚗️ development<a name="development"></a> <small><sup>top ▲</sup></small>

this section explains how to build mommy from source, in case you want to help with development or for any other reason~

<details> <summary>🎬 run</summary>

you can actually just directly run the script in src/main/sh/mommy. the only difference will be that the -h and -v options may not work correctly. if that annoys you, run make build after each change, and use build/bin/mommy instead~

</details> <details> <summary>🧪 tests</summary>
  1. requirements
    shellspec
  2. test local code
    1. all tests 
      make test
    2. unit tests 
      make test/unit
    3. integration tests 
      make test/integration
  3. test installed code 
    make system=1 test
  4. configuration
    except for system=1, test behaviour is configured with environment variables. check the various files in src/test/ to find 'em all~
</details> <details> <summary>🏬 distribution</summary>

mommy is distributed in three ways:

let's go into them in more detail~

</details> <details> <summary>📯 release</summary>

main always contains the latest stable version. to release a new version, just use the deploy action, which can be activated using a workflow_dispatch event~

<b>release checklists</b>

</details>

💖 acknowledgements<a name="acknowledgements"></a> <small><sup>top ▲</sup></small>

mommy recognises all contributors, no matter the size of the contribution. if mommy should add, remove, or change anything here, open an issue or contact the author~