Skip to content

Latest commit

 

History

History
126 lines (89 loc) · 6.51 KB

README.md

File metadata and controls

126 lines (89 loc) · 6.51 KB

hermes

Delivers setup and configuration for Ubuntu like a god.

About

hermes configures Ubuntu by installing various packages and (re-)placing configuration files. The setup is mostly unopinionated, non-intrusive, and tries to enhance the out-of-the-box experience of Ubuntu. Optionally, configuration of the GUI is supported. hermes is built for x86_64 (full support) and aarch64 (only non-GUI).

Usage

Note

While optional, I recommend running sudo apt-get --yes update && sudo apt-get --yes upgrade before using hermes.

To download the latest version of hermes, run the following commands:

HERMES_VERSION="$(curl -sSIL -w '%{url_effective}' -o /dev/null "https://github.com/georglauterbach/hermes/releases/latest" | sed 's|.*/||')"
sudo curl --silent --show-error --fail --location --output /usr/local/bin/hermes "https://github.com/georglauterbach/hermes/releases/download/${HERMES_VERSION}/hermes-${HERMES_VERSION}-$(uname -m)-unknown-linux-musl"
sudo chmod +x /usr/local/bin/hermes

To see the help message and install hermes, run the following commands:

hermes --help
hermes

To update hermes, run the following command

hermes --version
hermes --update --non-interactive # works properly on >= v4.0.0

Caution

hermes overwrites files like .bashrc. You should make a backup of your Bash configuration files before running hermes. You can later re-introduce the code from your .bashrc into a new file [1].

Optional Additional Setup

Bash

The setup of Bash is performed by ${HOME}/.bashrc and scripts in ${HOME}/.config/bash/. These setup files can be found here.

If you want to modify the behavior of hermes, take a look at {HOME}/.config/bash/20-custom_early.sh. This file contains variables that control the initialization of programs and their overrides as well as other configurations. The "Programs" section below refers to these variables.

To add code that would normally go to .bashrc, edit ${HOME}/.config/bash/99-custom_late.sh. These two files are not overwritten by hermes if you run hermes again.

Programs

hermes installs additional programs into ${HOME}/.local/bin/. These programs include:

  • Atuin
    • "magical" shell history using SQLite rather than a file
    • enabled with HERMES_INIT_ATUIN
    • CTRL+e (or up-arrow when HERMES_CONFIG_ATUIN_DISABLE_UP_ARROW=false) brings up the history
    • setting HERMES_CONFIG_ATUIN_DB_FILE changes the database file
  • bat
    • cat with syntax highlighting and git integration
    • enabled with HERMES_INIT_BAT, override cat with HERMES_OVERRIDE_CAT_WITH_BAT
  • ble.sh
    • command line editor written in pure Bash which replaces the default GNU Readline
    • enabled with HERMES_INIT_BLE_SH
  • eza
    • fast, modern alternative to ls
    • override ls with HERMES_OVERRIDE_LS_WITH_EZA
  • fd
    • fast, modern alternative to find
    • override find with HERMES_OVERRIDE_FIND_WITH_FD
  • fzf
    • general-purpose command-line fuzzy finder
    • enabled with HERMES_INIT_FZF
  • gitui
    • a fast, modern TUI for git
  • ripgrep
    • fast, modern alternative to grep
    • override grep with HERMES_OVERRIDE_GREP_WITH_RIPGREP
  • starship
    • minimal, blazing-fast, and infinitely customizable prompt for any shell
    • enabled with HERMES_INIT_STARSHIP
  • zoxide
    • smarter cd command
    • enabled with HERMES_INIT_ZOXIDE, override cd with HERMES_OVERRIDE_CD_WITH_ZOXIDE
  • zellij
    • terminal workspace with batteries included

Changing APT Sources

To change and add APT sources (including PPAs), run hermes with the --change-apt-sources (or -c) flag. This option installs a new ubuntu.sources file in /etc/apt/sources.list.d/ and adds additional PPAs for git, neovim, and flatpak.

GUI

To set up a GUI with Regolith Linux, run hermes with the --gui flag. This option installs new PPAs for Regolith Linux (Alacritty, Cryptomator, Regolith itself, and Visual Studio Code. Configurations for these packages is not provided automatically. In examples/gui/, you will find directories that are typically located in ${HOME}. You can copy the subdirectories of the directories to ${HOME}/.config/ to acquire my configurations.

Manual Setup Steps

There are programs and configuration files that you may want to install manually. These include:

  1. Rofi: A patched version of rofi that better integrates into Wayland
  2. Icons: Setup icon packs with the scripts/setup_icons.sh script

Supplementary Setup Scripts

You can find additional setup scripts that aid in setting up machines under the scripts/ directory.

Examples

You can find setup examples in the examples/ directory, e.g. for a custom post-hermes Bash setup, the GUI setup (including a Regolith, Waybar, and Alacritty configuration), VS Code configuration files, etc.

Architecture

hermes is written in the Rust programming language. As it performs a lot of network requests and disk I/O, it utilizes asynchronous programming with the tokio runtime. hermes performs four main tasks:

  1. Downloading and placing unversioned configuration files.
  2. Downloading and placing versioned configuration files.
  3. Setting up APT (optionally) and installing additional programs with it.
  4. Installing additional programs by downloading them from GitHub and unpacking them.

All of these tasks are performed asynchronously, which gives the illusion of parallelism (especially in the log). This makes hermes extremely fast.

Most configuration is stored in the data/ directory and is downloaded onto the target system.