Simple Bash scripting library.
Easy-to-use yet powerful library set of functions for Bash. The goal is not to replace traditional idioms but to provide a toolbox to boost your scripting productivity.
The project is under active development.
- Features
- Installation and Configuration
- Usage
- Contributing
- To-Do list
- Roadmap
- Credits and Acknowledgments
- Copyright and Licensing
- Changelog and News
- Notes and References
get_version
: Output Shellib version tostdout
is_root
: Return boolean status, if the current user is a root, or not (idiomatic[ "$EUID" -ne 0 ]
is not easily testable as$EUID
is read-only)event 'message' ['level' ['symbol' ['command']]]
: Send "command symbol message" tostderr
, defaultlevel
=$level_info
, defaultsymbol
depends on thelevel
($level_err
โ,$level_sec
โ ,$level_warn
โ ,$level_notice
๐, default$level_info
โ), and defaultcommand
is$0
err
,sec
,warn
,notice
, andinfo
functions -func 'message' ['symbol' ['command']]
: Wrappers for each level, defaultsymbol
depends on thelevel
, and defaultcommand
is$0
pkgs install 'man:pkg1' ['man:pkg2' [...]]
: Install packages from the package list formatted asman:pkg
, whereman
is a supported package manager, andpkg
is a package to install, supported package managers:apt
for deb packages byapt
pip
for Python packages bypip3
npm
for npm packages bynpm
snap
for Snap packagescurl2bash
for package specificationcommand=URL
- if a command exists, then the package is marked as installed. If doesn't, it is installed source bycurl -s "$URL" | bash
apt_add 'repository specification' 'repository_key_URL'
: Add apt repository by apt, equivalent tocurl -fsSL 'repository_key_URL' | apt-key add - && apt-add-repository 'repository specification' && apt-get update
- Status codes:
$status_ok
0,$status_err
1 - Symbols:
$symbol_err
โ,$symbol_sec
โ ,$symbol_warn
โ ,$symbol_notice
๐,$symbol_ok
โ,$symbol_tip
๐ก,$symbol_todo
โ,$symbol_doing
โฆ,$symbol_done
๐น,$symbol_failed
โ - Event levels:
$level_err
<$level_sec
<$level_warn
<$level_notice
<$level_info
shellib_latest_deb_url=$(curl https://gitlab.com/api/v4/projects/26143455/releases | jq --raw-output '.[0].assets.links | .[0].direct_asset_url') # Get the latest deb package URL
shellib_downloaded_deb_file=$(mktemp --suffix='deb') # Set the package download destination
curl "$shellib_latest_deb_url" -o "$shellib_downloaded_deb_file" # Download the latest deb package
sudo dpkg -i "$shellib_downloaded_deb_file" # Install the package
rm "$shellib_downloaded_deb_file" # Clean up after yourself
Install:
cd your-project/path/to/submodule # Get to the directory
git submodule add https://github.com/xebis/shellib.git shellib # Add Shellib as a git submodule
# Previous command:
# - updates (or creates, when doesn't exist) .gitmodules
# - stages .gitmodules and the new submodule
# Commit, push, ...
Update:
git submodule update path/to/submodule --remote --merge # Update the submodule
# OR
git submodule update --remote --merge # Updates all repository submodules
# Commit, push, ...
Recommended, but not necessary:
#!/usr/bin/env bash
# Use Bash Strict Mode, see http://redsymbol.net/articles/unofficial-bash-strict-mode/
set -euo pipefail
IFS=$'\n\t'
# Set safe basic locale
LANG=C
Source the library:
. /usr/lib/shellib.sh # When installed as a deb package
# OR
. path/to/submodule/shellib/shellib.sh # When added as a git submodule
Use library functions:
out 'Hello world!' '๐'
# Result is similar to:
# your/script ๐ Hello world!
Please read CONTRIBUTING for details on our code of conduct, and the process for submitting merge requests to us.
-
Git hooks check a lot of things for you, including running automated tests
scripts/test full
-
Stuff inherited from repository-template should be tested there.
-
Make sure all non-inherited
scripts/*
work as expected, testing checklist: -
shellib.sh
andsrc/*
- covered by unit teststests/*.sh
-
scripts/*
scripts-
scripts/build
- covered by unit tests -
scripts/pack
-
scripts/set-ver
- covered by unit tests
-
-
GitLab CI
- Built DEB package, see Installation And Configuration
To test your changes in a different environment, you might try to run a Docker container and test it from there.
Run a disposal Docker container:
sudo docker run -it --rm -v "$(pwd)":/shellib alpine:latest
sudo docker run -it --rm -v "$(pwd)":/shellib --entrypoint bash node:latest
In the container:
cd shellib
# Set variables GL_TOKEN and GH_TOKEN when needed
# Put here commands from .gitlab-ci.yml job:before_script and job:script
# For example job test-full:
apk -U upgrade
apk add bats
bats tests
# Result is similar to:
# 1..1
# ok 1 dummy test
Build, and pack:
ver_next='1.5.25-alpha'
scripts/set-ver "$ver_next" # Set version at source codes
# ... Do not forget to commit the change
scripts/build # Create build at ./build
scripts/pack "$ver_next" # Create package at ./build
- Fix workaround for pre-commit
jumanjihouse/pre-commit-hooks
hookscript-must-have-extension
-*.bats
shouldn't be excluded - Fix workaround for pre-commit
local
hookshellcheck
- shellcheck has duplicated parameters from.shellcheckrc
, because these are not taken into account
- Find a satisfactory way how to manage (list, install, update) dependencies across various distributions and package managers
- Add pre-commit meta hooks
- Add jumanjihouse/pre-commit-hooks hook protect-first-parent
- Speed up CI/CD by preparing a set of Docker images with pre-installed dependencies for each CI/CD stage, or by cache for
apk
,pip
, andnpm
- Martin Bruลพina - Author
- MIT License
- Copyright ยฉ 2021 Martin Bruลพina
- GitHub - xebis/repository-template: Well-manageable and well-maintainable repository template. - a lot of stuff is inherited from there, including git hooks, GitLab CI, scripts, or Visual Studio Code suggested extensions
- GitHub - mvdan/sh: A shell parser, formatter, and interpreter with bash support; includes shfmt
- GitHub - koalaman/shellcheck: ShellCheck, a static analysis tool for shell scripts
- GitHub - bats-core/bats-core: Bash Automated Testing System