Utilities

A curated collection of bash utility functions and modules for streamlined shell scripting across macOS and Linux systems.

Overview

This repository provides 20+ reusable bash functions organized into modules covering package managers, version control, programming languages, and system utilities. The library is import-based: source import.sh once, then import only the modules a script actually needs — similar to selective imports in other languages.

Version: 1.3.0

Quick Start

Basic Usage

Source import.sh and import the modules you need:

source "$HOME/set-me-up/dotfiles/utilities/import.sh"

smu::import base
smu::import homebrew

Sourcing import.sh has no side effects: it only defines the smu::* functions. Modules are loaded on smu::import, each file is sourced at most once, and modules declare their own dependencies (importing homebrew automatically loads base).

Module resolution is local-first: a local checkout next to import.sh is used when present, then the cache (UTILITIES_CACHE_DIR), and only then a remote fetch pinned to the release matching UTILITIES_VERSION.

Namespaced Functions

Since 1.3.0 every function is defined under its module namespace — base::execute, system::cmd_exists, brew::brew_install, apt::install_package — which removes collisions between modules (e.g. the apt and pacman install_package). The unnamespaced pre-1.3.0 names remain available as compatibility shims, so existing scripts keep working; new code should prefer the namespaced names.

Remote Bootstrap

Without a local checkout, bootstrap the importer remotely (pin to a tag for production use):

source /dev/stdin <<<"$(curl -s "https://raw.githubusercontent.com/smeltery/utilities/v1.3.0/import.sh")"

smu::import base

Note: The /dev/stdin syntax is required due to bash 3.2 compatibility on macOS.

Legacy Facade

Sourcing utilities.sh still works and loads the whole library (filtered by UTILITIES_MODULES), preserving the historical behavior for existing consumers:

source /dev/stdin <<<"$(curl -s "https://raw.githubusercontent.com/smeltery/utilities/v1.3.0/utilities.sh")"

New scripts should prefer import.sh with explicit imports.

Example Script

#!/bin/bash

# Load only what this script uses
source "$HOME/set-me-up/dotfiles/utilities/import.sh"

smu::import base
smu::import system
smu::import homebrew

# Use utility functions
bot "Starting setup..."

if is_macos; then
    action "Detected macOS"

    if ! cmd_exists "brew"; then
        error "Homebrew not found"
        exit 1
    fi

    brew_bundle_install -f "Brewfile"
    success "Homebrew packages installed"
fi

ok "Setup complete!"

Available Modules

Module	Description	Platform
base	Core utility functions (prompts, colors, spinners, execution)	All
system	OS detection, path management, file operations	All
network	Network utilities	All
homebrew	Homebrew package manager functions	macOS, Linux
macports	MacPorts package manager functions	macOS
gofish	Gofish package manager functions	All
apt	APT package manager functions	Debian/Ubuntu
pacman	Pacman package manager functions	Arch Linux
git	Git repository utilities	All
fish	Fish shell utilities and plugin managers	All
npm	Node.js and npm utilities	All
pip	Python pip utilities	All
pip3	Python pip3 utilities	All
pyenv	Python version manager utilities	All
gem	Ruby gem utilities	All
cargo	Rust cargo utilities	All
go	Go language utilities	All
sdkman	Java SDKMAN utilities	All

Key Features

🎨 Rich Output Functions

• Color-coded messages (success, error, warning, action)
• Interactive prompts with confirmation
• Progress spinners for long-running commands

🔧 System Utilities

• Cross-platform OS detection
• PATH management
• File operations (symlinks, extraction, directory creation)
• Shell configuration helpers

📦 Package Manager Integration

• Unified interface for multiple package managers
• Conditional loading based on platform
• Brewfile support with optional Python-based installer

🔐 Security Considerations

• Scripts are sourced directly from GitHub
• Recommendation: Review code before using in production
• Best Practice: Pin to specific version tags
• Optional: Cache scripts locally for offline/airgapped environments

Advanced Usage

Debug Mode

Enable verbose logging to see which modules are being loaded:

export UTILITIES_DEBUG=true
source /dev/stdin <<<"$(curl -s "https://raw.githubusercontent.com/smeltery/utilities/v1.0.0/utilities.sh")"

Selective Module Loading

Prefer explicit imports per script:

source "$HOME/set-me-up/dotfiles/utilities/import.sh"

smu::import homebrew
smu::import git

Fine-grained names are also supported (e.g. smu::import pip3 instead of the whole python group, or a path such as smu::import homebrew/brew).

When using the legacy utilities.sh facade, UTILITIES_MODULES filters which module groups are loaded:

export UTILITIES_MODULES="homebrew,git"
source /dev/stdin <<<"$(curl -s "https://raw.githubusercontent.com/smeltery/utilities/v1.3.0/utilities.sh")"

Pinning the Remote Ref

Remote fetches are pinned to the release tag matching UTILITIES_VERSION (falling back to master when the tag is unavailable). Override with UTILITIES_REF:

export UTILITIES_REF="v1.3.0"

Local Caching

Cache scripts locally to improve performance and enable offline usage:

export UTILITIES_CACHE_DIR="$HOME/.cache/smeltery/utilities"
source "$HOME/set-me-up/dotfiles/utilities/import.sh"

Documentation

• Function Reference - Complete list of all available functions
• Module Documentation - Detailed documentation for each module
• Dependencies - Requirements for each module
• Contributing - Guidelines for contributors
• Security - Security best practices and considerations
• Changelog - Version history and changes

Requirements

• Bash: 3.2+ (macOS default) or 4.0+
• curl: Required for remote sourcing
• Module-specific dependencies: See DEPENDENCIES.md

Platform Support

• ✅ macOS (Darwin) - All versions
• ✅ Ubuntu/Debian Linux
• ✅ Arch Linux
• ⚠️ Other Linux distributions - Base functionality supported, some modules may require adaptation

Testing

The repository includes comprehensive testing:

Shellcheck validation:

./tests/main.sh

Integration tests:

./tests/integration_test.sh

Tests run automatically on push via GitHub Actions for both Ubuntu and macOS.

Reproducible dev environment (Flox)

A Flox manifest at .flox/env/manifest.toml pins the toolchain CI uses — bash, shellcheck, and nodejs (for npx markdownlint-cli2). Activating it gives contributors the same versions on macOS or Linux, avoiding the "works in CI but not locally" gap:

# From the utilities/ directory:
flox activate

# Inside the activated shell you can run the same checks CI runs:
./tests/main.sh
./tests/integration_test.sh
npx markdownlint-cli2 "**/*.md"

Pinning bash here is especially valuable: the library targets bash 3.2 (macOS default) and a pinned bash version makes regression tests against that floor reproducible.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

Licensed under PolyForm Shield 1.0.0. See LICENSE for details.

Acknowledgments

This collection has been curated and refined over years of dotfile management and system automation. Many functions are inspired by or adapted from various open-source projects and community contributions.

---

Questions? Open an issue on GitHub. Want to help? Check out CONTRIBUTING.md.