{"id":13537204,"url":"https://github.com/vlisivka/bash-modules","last_synced_at":"2026-03-13T01:33:32.130Z","repository":{"id":3867937,"uuid":"11182651","full_name":"vlisivka/bash-modules","owner":"vlisivka","description":"Useful modules for bash","archived":false,"fork":false,"pushed_at":"2025-08-27T10:53:24.000Z","size":500,"stargazers_count":143,"open_issues_count":2,"forks_count":16,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-12-20T12:27:38.243Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-2.1","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vlisivka.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2013-07-04T16:58:34.000Z","updated_at":"2025-11-19T11:12:29.000Z","dependencies_parsed_at":"2025-05-31T12:12:09.933Z","dependency_job_id":"77f7d65d-5c2a-424c-860d-7cd9c70166bc","html_url":"https://github.com/vlisivka/bash-modules","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/vlisivka/bash-modules","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vlisivka%2Fbash-modules","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vlisivka%2Fbash-modules/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vlisivka%2Fbash-modules/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vlisivka%2Fbash-modules/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vlisivka","download_url":"https://codeload.github.com/vlisivka/bash-modules/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vlisivka%2Fbash-modules/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30453713,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-12T21:31:01.033Z","status":"ssl_error","status_checked_at":"2026-03-12T21:30:43.161Z","response_time":114,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T09:00:56.249Z","updated_at":"2026-03-13T01:33:32.108Z","avatar_url":"https://github.com/vlisivka.png","language":"Shell","readme":"* [bash-modules](#bash-modules)\n   * [Simple module system for bash.](#simple-module-system-for-bash)\n   * [Syntax](#syntax)\n   * [Example](#example)\n   * [License](#license)\n   * [Vision](#vision)\n   * [Features](#features)\n   * [TODO](#todo)\n   * [Showcase - log module](#showcase---log-module)\n   * [Showcase - arguments module](#showcase---arguments-module)\n   * [Showcase - strict mode](#showcase---strict-mode)\n   * [Error handling](#error-handling)\n      * [Chain of errors](#chain-of-errors)\n      * [Panic](#panic)\n\nbash-modules\n============\n\nSee documentation in [HTML format](http://vlisivka.github.io/bash-modules/).\n\n## Simple module system for bash.\n\nModule loader and collection of modules for bash scripts, to quickly write safe bash scripts in unofficial bash strict mode.\n\nCurrently, bash-modules project is targetting users of Linux OS, such as system administrators.\n\nbash-modules is developed at Fedora Linux and requires bash 4 or higher.\n\n## Syntax\n\nTo include module(s) into your script (note the \".\" at the beginning of the line):\n\n```\n. import.sh MODULE[...]\n```\n\nTo list available modules and show their documentation call import.sh as a command:\n\n```\nimport.sh [OPTIONS]\n```\n\nNOTE: Don't be confused by `import` (without `.sh`) command from `ImageMagick` package. `bash-modules` uses `import.sh`, not `import`.\n\n## Example\n\n```bash\n#!/bin/bash\n. import.sh log\ninfo \"Hello, world!\"\n```\n\nSee more examples in [bash-modules/examples](https://github.com/vlisivka/bash-modules/tree/master/bash-modules/examples) directory.\n\n## License\n\n`bash-modules` is licensed under terms of LGPL2+ license, like glibc. You are not allowed to copy-paste the code of this project into an your non-GPL-ed project, but you are free to use, modify, or distribute `bash-modules` as a separate library.\n\n## Vision\n\nMy vision for the project is to create a loadable set of bash subroutines, which are:\n\n  * useful;\n  * work in strict mode (set -ue);\n  * correctly handle strings with spaces and special characters;\n  * use as little external commands as possible;\n  * easy to use;\n  * well documented;\n  * well covered by test cases.\n\n## Features\n\n* module for logging;\n* module for parsing of arguments;\n* module for unit testing;\n* full support for unofficial strict mode.\n\n## Installation\n\nUse `install.sh` script in bash-modules directory to install bash-modules\nto `~/.local` (default for a user) or `/usr/local/bin` (default for a\nroot user). See `./install.sh --help` for options.\n\n\n## TODO\n\n* [x] Implement module loader.\n* [x] Implement few modules with frequently used functions and routines.\n* [ ] Cooperate with other bash-related projects.\n* [ ] Implement a repository for extra modules.\n* [ ] Implement a package manager for modules or integrate with an existing PM.\n\n## Showcase - log module\n\n```bash\n#!/bin/bash\n. import.sh strict log arguments\n\nmain() {\n  debug \"A debug message (use --debug option to show debug messages).\"\n\n  info \"An information message. Arguments: $*\"\n\n  warn \"A warning message.\"\n\n  error \"An error message.\"\n\n  todo \"A todo message.\"\n\n  unimplemented \"Not implemented.\"\n}\n\narguments::parse -- \"$@\" || panic \"Cannot parse arguments.\"\n\ndbg ARGUMENTS\n\nmain \"${ARGUMENTS[@]}\"\n```\n\n![Output](https://raw.githubusercontent.com/vlisivka/bash-modules/master/images/showcase-log-1.png)\n\n![Output](https://raw.githubusercontent.com/vlisivka/bash-modules/master/images/showcase-log-2.png)\n\n## Showcase - arguments module\n\n\n```bash\n#!/bin/bash\n. import.sh strict log arguments\n\nNAME=\"John\"\nAGE=42\nMARRIED=\"no\"\n\n\nmain() {\n  info \"Name: $NAME\"\n  info \"Age: $AGE\"\n  info \"Married: $MARRIED\"\n  info \"Other arguments: $*\"\n}\n\narguments::parse \\\n  \"-n|--name)NAME;String,Required\" \\\n  \"-a|--age)AGE;Number,(( AGE \u003e= 18 ))\" \\\n  \"-m|--married)MARRIED;Boolean\" \\\n  -- \"$@\" || panic \"Cannot parse arguments. Use \\\"--help\\\" to show options.\"\n\nmain \"${ARGUMENTS[@]}\" || exit $?\n\n# Comments marked by \"#\u003e\u003e\" are shown by --help.\n# Comments marked by \"#\u003e\" and \"#\u003e\u003e\" are shown by --man.\n\n#\u003e Example of a script with parsing of arguments.\n#\u003e\u003e\n#\u003e\u003e Usage: showcase-arguments.sh [OPTIONS] [--] [ARGUMENTS]\n#\u003e\u003e\n#\u003e\u003e OPTIONS:\n#\u003e\u003e\n#\u003e\u003e   -h|--help       show this help screen.\n#\u003e\u003e   --man           show complete manual.\n#\u003e\u003e   -n|--name NAME  set name. Name must not be empty. Default name is \"John\".\n#\u003e\u003e   -a|--age  AGE   set age. Age must be \u003e= 18. Default age is 42.\n#\u003e\u003e   -m|--married    set married flag to \"yes\". Default value is \"no\".\n#\u003e\u003e\n```\n\n![Output](https://raw.githubusercontent.com/vlisivka/bash-modules/master/images/showcase-arguments-1.png)\n\n\n![Output](https://raw.githubusercontent.com/vlisivka/bash-modules/master/images/showcase-arguments-2.png)\n\n\n![Output](https://raw.githubusercontent.com/vlisivka/bash-modules/master/images/showcase-arguments-3.png)\n\n## Showcase - strict mode\n\n```bash\n#!/bin/bash\n. import.sh strict log\na() {\n  b\n}\nb() {\n  c\n}\nc() {\n  d\n}\nd() {\n  false\n}\n\na\n\n```\n\n![Output](https://raw.githubusercontent.com/vlisivka/bash-modules/master/images/showcase-strict-mode.png)\n\n## Error handling\n\n`bash-modules` `log` module supports two strategies to handle errors:\n\n### Chain of errors\n\nThe first, strategy is to report the error to user, and then return error code from the function, to produce chain of errors. This technique allows for system administrator to understand faster - why script failed and what it tried to achieve.\n\n```bash\n#!/bin/bash\n. import.sh strict log\nfoo() {\n  xxx || { error \"Cannot execute xxx.\"; return 1; }\n}\n\nbar() {\n  foo || { error \"Cannot perform foo.\"; return 1; }\n}\n\nmain() {\n  bar || { error \"Cannot perform bar.\"; return 1; }\n}\n\nmain \"$@\" || exit $?\n```\n\n```text\n$ ./chain-of-errors.sh\n./chain-of-errors.sh: line 4: xxx: command not found\n[chain-of-errors.sh] ERROR: Cannot execute xxx.\n[chain-of-errors.sh] ERROR: Cannot perform foo.\n[chain-of-errors.sh] ERROR: Cannot perform bar.\n```\n\n### Panic\n\nThe second strategy is just to panic, when error happened, and abort script. Stacktrace is printed automatically in this case.\n\n```bash\n#!/bin/bash\n. import.sh strict log\nxxx || panic \"Cannot execute xxx.\"\n```\n\n```text\n$ ./simple-panic.sh\n./simple-panic.sh: line 3: xxx: command not found\n[simple-panic.sh] PANIC: Cannot execute xxx.\n\t\tat main(./simple-panic.sh:3)\n```\n\nNOTE: If error happened in a subshell, then script author need to add another panic handler after end of subshell, e.g. `( false || panic \"foo\" ) || panic \"bar\"`.\n","funding_links":[],"categories":["Libraries","others","Shell","Shell Script Development"],"sub_categories":["Reusable Things","Directory Navigation"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvlisivka%2Fbash-modules","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvlisivka%2Fbash-modules","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvlisivka%2Fbash-modules/lists"}