libsh

Warning

During pre-1.0 development (0.x), this project will regularly introduce breaking changes without a major version bump. Public APIs, file layouts, and command-line interfaces may change between releases. Pin a release for reproducible builds and review its release notes before updating. Stable compatibility guarantees will begin with version 1.0.0.

An open-source MIT-licensed Bash library maintained by Ad Noctem Collective for Bash 4.0 and above. It provides reusable functions for filesystem operations, data conversion, networking, logging, argument parsing and system administration, with optional extensions for domain-specific tasks.

The lib directory contains core modules, loaded through a single entrypoint. A default installation includes core only; extensions are installed and loaded explicitly. The scripts directory holds operational scripts for direct execution by users, init systems and automation.

Standalone executables in bin handle distribution: install bootstraps libman to manage a shared installation, while libtree vendors core and selected addons through Git subtree. You can also reuse the repository through Git submodules. See the installation guide for installation paths, selective bundles, updates and container usage.

✨ TL;DR

Install core and configure your shell. The installer can add a LIBSH_DIR export to your Bash or Zsh rc file; it does not load library functions or change PATH. Use the paths printed by the installer if you choose a custom or system-wide installation.

# Install core and opt in to a LIBSH_DIR export in ~/.bashrc (or use --init-shell zsh).
curl -fsSL https://raw.githubusercontent.com/adnoctem/libsh/main/bin/install | bash -s -- --init-shell bash

# For the default user installation, make libman available in this shell.
# Add this PATH line to your shell configuration yourself if needed.
export PATH="$HOME/.local/bin:$PATH"
export LIBSH_DIR="$(libman path)"

# Inspect the installation and update core and the standalone manager.
libman status
libman update
libman self-update

# Install optional addons matching the installed core release.
libman extension-add git secret
libman extensions

Run the following library examples in Bash 4.0+, including on macOS; its bundled Bash 3.2 is insufficient. The Bash manual explains the language and shell features used throughout the project. Start a fresh consuming shell after updating: already-sourced functions remain in existing shells.

# Load core; LIBSH_DIR points to the directory containing lib.sh.
source "$LIBSH_DIR/lib.sh"

# Log readable, timestamped messages. Debug is silent unless enabled.
lib::log::print_info 'Starting configuration'
LIBSH_DEBUG=true lib::log::print_debug 'Debug enabled for this call'
lib::log::print_success 'Core is ready'

# Keep calculations in bytes and format only for display.
bytes=$(lib::data::bytes_from 2 MiB)
lib::data::bytes_to "$bytes" KB 3   # 2097.152
lib::data::bytes_format "$bytes"    # 2.00 MiB

# Installing an addon does not load it; request it explicitly when needed.
lib::load_extensions git secret

Try an edit against a disposable configuration file. Editing uses POSIX extended regular expressions with sed-style replacement text. No match is an error. Default edits replace the file; --in-place retains the existing file object and can work in a nonwritable parent directory, but an interrupted write can leave partial contents.

source "$LIBSH_DIR/lib.sh"

config=$(mktemp /tmp/libsh-example.XXXXXXXX)
printf 'workers=2\n' >"$config"
lib::fs::file_replace_content "$config" '^workers=[0-9]+$' 'workers=4'
cat "$config" # workers=4

lib::fs::file_replace_content "$config" '^workers=[0-9]+$' 'workers=8' --in-place
cat "$config" # workers=8
rm -- "$config"

Operational scripts run from a checkout and have their own command dependencies. Inspect help and check prerequisites before invoking them; use --dry-run to preview supported state-changing operations.

./scripts/archive-create.sh --help
./scripts/archive-create.sh --check-prerequisites
./scripts/archive-create.sh --sources ./docs --output-dir /tmp/libsh-archives --dry-run

📚 Documentation

Document	What you will find
Architecture	Repository layout, core and extension boundaries, loading, runtime contracts and release flow.
API reference	Every public core and extension function, with arguments, return statuses, output behavior, dependencies and examples.
Installation and management	Bootstrap options, libman commands, addon selection, shell setup, container images and vendoring with libtree.
Contributing guidelines	Development setup, build and test commands, source formatting, function comments, conventional commits and release policy.
Nomenclature	File naming, approved script verbs, public namespaces and private helper conventions.
Agent guidance	Repository-specific instructions for coding agents, including supported Bash versions and required checks.
Code of Conduct	Participation expectations, private conduct reporting and maintainer enforcement.
Security policy	Private vulnerability reporting, version support, installation trust, privilege boundaries and handling secrets.
Source acknowledgements	Upstream tools, design references, installer examples and documentation inspiration.
TODO	Remaining work and ideas under consideration; completed work is recorded in Git history and release notes.

🔃 Contributing

Contributions are welcome via GitHub's Pull Requests. Fork the repository and implement your changes within the forked repository, after that you may submit a Pull Request.

Refer to the Contributing Guidelines for the build targets, coding conventions, and commit message format, and to NOMENCLATURE.md for how scripts and library functions are named. Participation follows the Code of Conduct. Report suspected vulnerabilities privately using the Security Policy.

📥 Maintainers

This project is owned and maintained by Ad Noctem Collective. Refer to the AUTHORS or CODEOWNERS for more information. You may also use the linked contact details to reach out directly.

©️ Copyright

Assets provided by: Icons8 LLC

Project references and upstream tools are listed in Source Acknowledgements.