Dorothy

Dorothy is a dotfile ecosystem featuring:

• seamless support for Bash, Zsh, Fish, Nu, Xonsh, Elvish, Dash, KSH
• seamless support for multiple operating systems and architectures
• seamless support for your favorite terminal and GUI editors
• automatic configuration of your environment variables for what you have installed on your system
• automatic installation and updating of your specified packages
• automatic Git, SSH, and GPG configuration based on what your system supports and your configuration
• hundreds of commands to improve your productivity
• completely extensible and configurable with your own user repository
• all this together, allows you to go from zero to hero within minutes, instead of days, on a brand new machine

Dorothy maintainers are daily driving Dorothy on:

• macOS on Apple Silicon (ARM64)
• macOS on Intel (x86_64)
• Ubuntu Server on Raspberry Pi 4 (ARM64)
• Ubuntu Desktop on Raspberry Pi 400 (ARM64)
• Ubuntu Desktop on Intel/AMD (x86_64)

Dorothy users are daily driving Dorothy on:

• Manjaro/Arch on Intel/AMD (x86_64)
• Windows 10 via Ubuntu WSL2 on Intel/AMD (x86_64)
• Windows 11 via Ubuntu WSL2 on Intel/AMD (x86_64)

Dorothy maintainers and users are occasionally driving Dorothy on:

• macOS on Apple Silicon with HOMEBREW_ARCH="x86_64"
• Fedora via Intel/AMD (x84_64) virtual machines
• OpenSUSE via Intel/AMD (x84_64) virtual machines
• Alpine via Intel/AMD (x84_64) virtual machines
• Alpine via Apple Silicon (ARM64) virtual machines
• Ubuntu Server on StarFive’s VisionFive (RISC-V)

Watch the 2022 April Presentation to see what Dorothy can do!

Setup

Prerequisites

macOS:

xcode-select --install

Windows 10/11:

# [Install WSL.](https://learn.microsoft.com/en-au/windows/wsl/install)
wsl --install
wsl --set-default-version 2
# note that [wsl --version] does not report WSL2, you need to do [wsl -l -v]

Ubuntu / Debian / Kali:

sudo apt-get update
sudo apt-get install bash curl

Fedora:

dnf check-update
dnf --refresh --best install bash curl

OpenSUSE / SUSE:

zypper --gpg-auto-import-keys refresh
zypper install bash curl

Alpine:

doas apk update
doas apk add bash curl grep

Manjaro:

pamac install bash curl

Arch:

pacman-key --init
pacman --refresh --sync --needed bash curl

Void:

xbps-install --sync --update xbps
xbps-install --sync bash curl

Mageia, Nix, and Gentoo are currently unsupported.

Try

You can trial Dorothy commands without configuring your shell.

To run a specific command in/from the Dorothy environment, enter the following, swapping out everything after the double-dash (--) with whatever command to run:

bash -ic "$(curl -fsSL https://dorothy.bevry.me/run)" -- echo-verbose -- a b c
# if your shell doesn't recognize any of the above syntax, run `bash -i` then try again

To run multiple commands in/from a Dorothy-configured REPL, enter the following line by line:

bash -ic "$(curl -fsSL https://dorothy.bevry.me/repl)"
# if your shell doesn't recognize any of the above syntax, run `bash -i` then try again

# now you can run whatever and how many commands as you'd like, such as:
echo-verbose -- a b c
echo-style --success=awesome

# once you are done, exit the trial environment
exit

Install

To install Dorothy enter the following in your favorite terminal application:

bash -ic "$(curl -fsSL https://dorothy.bevry.me/install)"
# if your shell doesn't recognize any of the above syntax, run `bash -i` then try again

During installation, Dorothy will ask you to create a repository to store your user configuration, such as a dotfiles repository. If you already have a dotfiles repository, you can use that, or make another.

Verify the installation worked by selecting a theme for Dorothy by running:

# you must open a new terminal instance first
dorothy theme
# then open a new terminal

To select your login shell, run setup-shell.

Troubleshooting

If packages are failing to install, go back to the "Prerequisites" section.

If your shell doesn't recognize any of the Dorothy commands (you get a command not found error, or an undefined/unbound variable error), then it could be that:

• Your shell is not running as a login shell. Verify that your Terminal is running the shell as a login shell.
• Dorothy did not configure itself for the shell you use. Re-run the Dorothy installation process, and be sure to configure Dorothy for your shell.
• Your login shell is not one of the Dorothy supported shells. Create an issue requesting support for your shell.

Overview

Dorothy Core

Dorothy installs itself to $DOROTHY, which defaults to the XDG location of ~/.local/share/dorothy, and consists of the following:

• commands directory contains executable commands of super-stable quality, they are actively used within the Dorothy core and by the users of Dorothy.
• commands.beta directory contains executable commands of beta quality, these are commands that require more usage or possible breaking changes before promotion to commands.
• config directory contains default configuration
• sources directory contains scripts that are loaded into the shell environment
• themes directory contains themes that you can select via the DOROTHY_THEME environment variable
• user directory is your own github repository for your custom configuration

For each shell that you configured during the Dorothy installation (can be reconfigured via the dorothy install command), the configured shell performs the following steps when you open a new shell instance via your terminal:

1. The shell loads Dorothy's initialization script:

   • Elvish loads our init.elv script
   • Fish loads our init.fish script
   • Nu loads our init.nu script
   • Xonsh loads our init.xsh script
   • POSIX shells (Bash, Zsh, Dash, KSH, etc) load our init.sh script

2. The initialization script will:

   1. Ensure the DOROTHY environment variable is set to the location of the Dorothy installation.

   2. If a login shell, it loads our login script sources/login.(bash|dash|elv|fish|ksh|nu|xsh|zsh), which will:

      1. Apply any configuration changes necessary for that login shell

      2. Load our environment script sources/environment.(bash|dash|elv|fish|ksh|nu|xsh|zsh), which will:

         1. Invoke commands/setup-environment-commands which determines and applies all necessary environment configuration changes to the shell. It loads your user/config(.local)/environment.bash configuration script for your own custom environment configuration that will be applied to all your login shells.

   3. If a login and interactive shell, it loads our interactive script sources/interactive.(bash|dash|elv|fish|ksh|nu|xsh|zsh), which will:

      1. Load your own user/config(.local)/interactive.(bash|dash|elv|fish|ksh|nu|xsh|zsh) configuration script for your own interactive login shell configuration.
         • Elvish will only load interactive.elv if it exists.
         • Fish will load interactive.fish if it exists, otherwise it will load interactive.sh.
         • Nu will only load interactive.nu and it must exist.
         • Xonsh will only load interactive.xsh if it exists.
         • POSIX shells (Bash, Zsh, Dash, KSH, etc) will load their interactive.(bash|zsh|...etc) file if it exists, otherwise they will load interactive.sh if exists.
      2. Load any common alias and function utilities.
      3. Load our theme configuration.
      4. Load our ssh configuration.
      5. Load our autocomplete configuration.

This is the foundation that enables Dorothy's hundreds of commands to work across hundreds of machines, across dozens of operating system and shell combinations, seamlessly.

Dorothy User Configuration

Your user configuration goes to the XDG location of ~/.local/config/dorothy which Dorothy symlinks to ~/.local/share/dorothy/user, your user configuration consists of the following:

• commands directory, for public commands
• commands.local directory, for private commands (git ignored by default)
• config directory, for public configuration
• config.local directory, for private configuration (git ignored by default)

The order of preference within Dorothy is (commands|config).local first, then (commands|config), then Dorothy's own (commands|config) then everything else.

You can find the various configuration files that are available to you by browsing Dorothy's default config directory.

Showcase

Use these sources to find inspiration for your own user commands and configuration.

• Dorothy's commands directory for super-stable commands with up to date conventions.
• Dorothy's commands.beta directory for beta-quality commands with possibly outdated conventions.
• Dorothy User Configurations:
  • @balupton / dotfiles: uses Fish as login shell, plenty of Bash commands
  • @molleweide / dotfiles: uses Zsh as login shell, plenty of Bash commands, kmonad user
  • @jondpenton / dotfiles: uses Nu as login shell, plenty of Nu commands
  • if you use Dorothy, send a pull request to add your own user configuration to this list.

Community

Join the Bevry Software community to stay up-to-date on the latest Dorothy developments and to get in touch with the rest of the community.

Backers

Code

Discover how to contribute via the CONTRIBUTING.md file.

Authors

• Benjamin Lupton — Accelerating collaborative wisdom.

Maintainers

• Benjamin Lupton — Accelerating collaborative wisdom.

Contributors

• Benjamin Lupton — view contributions
• Bevry Team — view contributions
• BJReplay — view contributions
• molleweide — view contributions
• Nutchanon Ninyawee — view contributions
• Sumit Rai — view contributions

Finances

Sponsors

• Andrew Nesbitt — Software engineer and researcher
• Balsa — We're Balsa, and we're building tools for builders.
• Codecov — Empower developers with tools to improve code quality and testing.
• Frontend Masters — The training platform for web app engineering skills – from front-end to full-stack! 🚀
• Mr. Henry
• Poonacha Medappa
• Rob Morris
• Sentry — Real-time crash reporting for your web apps, mobile apps, and games.
• Syntax — Syntax Podcast

Donors

• Andrew Nesbitt
• Balsa
• Chad
• Codecov
• entroniq
• Frontend Masters
• Jean-Luc Geering
• Michael Duane Mooring
• Mohammed Shah
• Mr. Henry
• Poonacha Medappa
• Rob Morris
• Sentry
• ServieJS
• Syntax

License

Unless stated otherwise all works are:

• Copyright © Benjamin Lupton

and licensed under:

• Reciprocal Public License 1.5