{"id":13587340,"url":"https://github.com/adoyle-h/lobash","last_synced_at":"2025-04-09T06:12:02.382Z","repository":{"id":63619360,"uuid":"98386647","full_name":"adoyle-h/lobash","owner":"adoyle-h","description":"A modern, safe, powerful utility/library for Bash script development.","archived":false,"fork":false,"pushed_at":"2024-09-14T20:04:24.000Z","size":757,"stargazers_count":381,"open_issues_count":0,"forks_count":29,"subscribers_count":9,"default_branch":"develop","last_synced_at":"2025-04-02T04:58:29.361Z","etag":null,"topics":["bash","bash-script","bashrc","linux","shell","shell-script","utility"],"latest_commit_sha":null,"homepage":"https://github.com/adoyle-h/lobash/blob/develop/docs/module-usages/README.md","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/adoyle-h.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"docs/CONTRIBUTING.md","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},"funding":{"patreon":"adoyle_h","liberapay":"adoyle","custom":["https://media.githubusercontent.com/media/adoyle-h/_imgs/master/sponsor.png"]}},"created_at":"2017-07-26T06:17:59.000Z","updated_at":"2025-03-30T01:26:41.000Z","dependencies_parsed_at":"2024-09-15T04:56:28.253Z","dependency_job_id":null,"html_url":"https://github.com/adoyle-h/lobash","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adoyle-h%2Flobash","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adoyle-h%2Flobash/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adoyle-h%2Flobash/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adoyle-h%2Flobash/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/adoyle-h","download_url":"https://codeload.github.com/adoyle-h/lobash/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247987285,"owners_count":21028895,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["bash","bash-script","bashrc","linux","shell","shell-script","utility"],"created_at":"2024-08-01T15:06:09.905Z","updated_at":"2025-04-09T06:12:02.346Z","avatar_url":"https://github.com/adoyle-h.png","language":"Shell","funding_links":["https://patreon.com/adoyle_h","https://liberapay.com/adoyle","https://media.githubusercontent.com/media/adoyle-h/_imgs/master/sponsor.png"],"categories":["Shell","Shell Script Development"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"Lobash Logo\" src=\"./docs/imgs/lobash.svg\"\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  A modern, safe, powerful utility/library for Bash script development.\n\u003c/p\u003e\n\n[English](./README.md) | [中文](./README.zh.md)\n\n## What is Lobash?\n\nDue to its complex syntaxes and symbols, and Unix commands different options and behaviors in same name (such like GNU `sed` and BSD `sed` are different),\nBash script development is complex and fallible.\n\nJavascript has a powerful library [Lodash](https://github.com/lodash/lodash) for simplifying development.\nSo I build Lobash to do similar works for shell development.\n\nLobash provides collections of functions to improve efficiency of shell development.\nIt is compatible with Bash 4.0+ and MacOS/Linux/Alpine/Busybox systems.\n\nIt is implemented with pure bash script. (Except [l.now](src/modules/now.bash) function. It uses perl functions.)\n\n## Features\n\n- Modular and easy to use. One module one Function.\n- Semantic functions instead of recondite bash expressions, substitutions, expansions.\n- Rich Functions. Over [140+ modules][module-usages] provided.\n  - 15 Categories: Arithmetic, Array, Color, Condition, Console, Debug, File, Path, Prompt, String, System, Terminal, Time, Util, Variable.\n  - Each function is [documented][module-usages].\n- Robust and Safe. Over [700+ test cases](./tests/modules/) passed in [Github Actions](https://github.com/adoyle-h/lobash/actions).\n- Fast. 0.058s to load Lobash completely.\n- Compatible with MacOS/Linux/Alpine/Busybox systems.\n- Compatible with Bash 4.0 and higher versions.\n\n## Design philosophy\n\n### One Feature only with One Function\n\nIf a function needs to pass much arguments and combine much functions to accomplish this, it does not conform to the design philosophy of Lobash.\n\nFor example, a logger library could be as simple as `l.log() { echo \"$1\" \u003e\u003e \"$2\"; }`, calling `l.log \"message\" \"/var/log/file\"` to append a log.\nIt could also be complex. With many features such as Colorful Highlights, Formatting, Caller Location, Log Level, Log Storages, Log Rotation.\n\nLobash provides the simplest and easy-to-use functions. For complex features, please search for other projects. Here are a few recommended projects.\n\n- [ebash](https://github.com/elibs/ebash): implements many complex features.\n- Logger: [b-log](https://github.com/idelsink/b-log) or [bash-logger](https://github.com/adoyle-h/bash-logger)\n- Colors: [shell-general-colors](https://github.com/adoyle-h/shell-general-colors)\n\n### No Side Effects\n\nA function has only input and output, no side effects. When the same input is given, it will always return the same output.\n\nLobash does not modify global variables. No internal variables are created to store intermediate state (ideally).\n\nHowever, Lobash will modify user-passed variables to store the result of the computation in it. e.g., [`l.parse_params`](./example/modules/parse_params).\n\n### Reducing Implicit Errors\n\nBash's syntaxes and behaviors are too weird.\nLobash provides semantic functions that implement a single feature to keep it simple.\n\nLobash helps to reduce the mental burden on developers.\n\n## CI Status\n\n- [develop branch](https://github.com/adoyle-h/lobash/tree/develop): [![CI Status](https://github.com/adoyle-h/lobash/actions/workflows/ci.yaml/badge.svg?branch=develop)](https://github.com/adoyle-h/lobash/actions/workflows/ci.yaml?query=branch%3Adevelop)\n- [v0.7.0](https://github.com/adoyle-h/lobash/tree/v0.7.0): [![CI Status](https://github.com/adoyle-h/lobash/actions/workflows/ci.yaml/badge.svg?branch=v0.7.0)](https://github.com/adoyle-h/lobash/actions/workflows/ci.yaml?query=branch%3Av0.7.0)\n- [v0.6.0](https://github.com/adoyle-h/lobash/tree/v0.6.0): [![CI Status](https://github.com/adoyle-h/lobash/actions/workflows/ci.yaml/badge.svg?branch=v0.6.0)](https://github.com/adoyle-h/lobash/actions/workflows/ci.yaml?query=branch%3Av0.6.0)\n- [v0.5.1](https://github.com/adoyle-h/lobash/tree/v0.5.1): [![CI Status](https://github.com/adoyle-h/lobash/actions/workflows/ci.yaml/badge.svg?branch=v0.5.1)](https://github.com/adoyle-h/lobash/actions/workflows/ci.yaml?query=branch%3Av0.5.1)\n\n## Versions\n\nRead [tags][] for versions.\nThe versions follow the rules of [Semantic Versioning 2.0.0](http://semver.org/spec/v2.0.0.html).\n\n## [ChangeLog](./CHANGELOG.md)\n\n## [FAQ](./docs/faq.md)\n\n## Prerequisites\n\n### Supported Platform\n\n| Supported | Platform | Version | Main Reasons                       |\n|:---------:|:---------|:--------|:-----------------------------------|\n|     ✅    | MacOS    | *       | -                                  |\n|     ✅    | Linux    | *       | -                                  |\n|     ✅    | Busybox  | *       | -                                  |\n|     ✅    | Alpine   | *       | -                                  |\n|     ❔    | BSD      | -       | Not tested yet. Maybe not support. |\n|     🚫    | Windows  | -       | Never and ever supported.          |\n\n### Supported Shells\n\n| Supported | Shell    | Version       | Descriptions                                  |\n|:---------:|:---------|:--------------|:----------------------------------------------|\n|     ✅    | Bash     | v5 and higher | Completely supported                          |\n|     ✅    | Bash     | v4.4          | Completely supported                          |\n|    ✅💬   | Bash     | v4.3          | -                                             |\n|    ✅💬   | Bash     | v4.2          | -                                             |\n|    ✅💬   | Bash     | v4.1          | -                                             |\n|    ✅💬   | Bash     | v4.0          | -                                             |\n|     🚫    | Bash     | v3            | Associative array is not supported until v4.0 |\n|     🚫    | POSIX sh | *             | `local` keyword not supported                 |\n|     🚫    | Zsh      | *             | -                                             |\n|     🚫    | Fish     | *             | -                                             |\n\nMost Lobash modules support Bash 4.0 and higher versions. Some modules are not compatible with Bash version earlier than 4.4. See the [list](./docs/module-usages/README.md#not-compatible).\nEach module annotates a `Bash` label in [module usages][module-usages].\n`Bash: 4.2+` means compatible with Bash 4.2 and higher versions.\n\n✅💬 means Lobash is compatible but not all modules supported in shell.\nIt will print notes to show what modules is not supported and ignored when building Lobash.\n\n**If you use Lobash with Bash 4.0~4.3. Please read [./docs/with-lower-version-bash.md](./docs/with-lower-version-bash.md) first. It's very important.**\n\n**Lobash not test with Bash 4.0 in MacOS and Linux. It seems a bug of Bash 4.0. Please contact me if you solved this problem.** Read [this document](./docs/with-lower-version-bash.md#not-test-with-bash-40).\n\nAlthough most Linux distributions use Bash v4.3 at the least, and MacOS installed Bash v3.2 by default,\nit is easily to upgrade Bash 4.4+ in most systems.\n\nBash below 4.4 have a lot of bugs. It's strongly advised to upgrade to Bash 4.4 or above.\n\n### Dependencies\n\nMake sure below dependencies have been installed in your system.\n\n- Linux commands:\n  - sed/grep/mktemp/dirname/basename/cd/printf/echo/wc\n  - sed: BSD and GNU are both compatible with Lobash\n\n## Installation\n\nAvailable Lobash versions refer to [Git Tags](https://github.com/adoyle-h/lobash/tags) which named like \"vX.Y.Z\".\n\n```sh\nVERSION=v0.7.0  # or VERSION=develop, but develop branch is unstable.\n# Download source codes\ngit clone --depth 1 --branch $VERSION https://github.com/adoyle-h/lobash.git\ncd lobash\n# This step is optional. Clone submodules only if you want to run test cases.\ngit submodule update --init --recursive --progress\n\n# Copy it to somewhere in your path\nsudo ln -s \"$PWD/build\" /usr/local/bin/lobash-gen\n```\n\n## Usage\n\n`lobash-gen -h` show help.\n\n### Build your lobash.bash\n\nFirst, build your own `lobash.bash` file by `lobash-gen`.\n\n```sh\n# Interactive build process, import all Lobash modules\nlobash-gen\n# Generated file: ./lobash.bash\n\n# Or build Lobash to specific path\nlobash-gen \u003ctarget-path\u003e\n# Generated file: \u003ctarget-path\u003e\n```\n\n**Read [./docs/build.md](./docs/build.md) for more details.**\n\n### Edit your scripts and set shell options\n\nAll Lobash modules are written and tested with the shell options:\n\n- `set -o errexit`\n- `set -o nounset`\n- `set -o pipefail`\n- `shopt -s inherit_errexit` (`inherit_errexit` is a new feature in Bash v4.4)\n\nIf you do not understand the meanings of these shell options,\nplease read [this article](https://dougrichardson.us/notes/fail-fast-bash-scripting.html).\n\n**Lobash not enable these options by default. Make sure the same shell options enabled before call Lobash functions in your scripts. Otherwise there may be unexpected behaviors with it.**\n\n### Load lobash.bash in your scripts\n\nSecond, load your own `lobash.bash` file in your scripts and all Lobash functions will be imported to current shell environment.\n\n```sh\n#!/usr/bin/env bash\n\nset -o errexit -o nounset -o pipefail -o errtrace  # You can remove \"-o errtrace\" if you do not use l.trap_error.\n(shopt -p inherit_errexit \u0026\u003e/dev/null) \u0026\u0026 shopt -s inherit_errexit\n\n# It will load all Lobash modules\nsource \u003cpath-to-lobash.bash\u003e\n# Call l.\u003cmodule_name\u003e when \"lobash-gen\"\nl.ask 'Hello Lobash?'\n\n# Call lobash.\u003cmodule_name\u003e when \"lobash-gen -p lobash_\"\n# lobash_ask 'Hello Lobash?'\n```\n\nLoad `lobash.bash` is fast, nearly 0.058s in fact.\n\n```sh\ntime source ./dist/lobash.bash\n\nreal    0m0.058s\nuser    0m0.022s\nsys     0m0.036s\n```\n\n### Module Usages and Documents\n\nRead all module usages in [./docs/module-usages/][module-usages].\n\nRead all module examples in [./example/modules](./example/modules) and [test cases](./tests/modules).\n\nAvailable modules list in [config.example](./config.example).\n\n## Advanced Usages\n\n### lobash-gen -c config\n\n`lobash-gen` will export all modules by default. You can export specific modules with `-c \u003cconfig\u003e` option.\n\nYou can also set `PREFIX`, `BASH_MIN_VERSION` in config.\n\n```sh\ncp config.example config\n# The \"config\" file is ignored by git\n\n# Edit config\nlobash-gen -c ./config\n```\n\n### [Command](./docs/lobash-command.md)\n\n## Who use Lobash\n\n- [one.bash](https://github.com/one-bash/one.bash)\n- Contact me to add your project to list.\n\n## Related Projects\n\n- [shell-general-colors](https://github.com/adoyle-h/shell-general-colors): shell colors\n- [bats-core](https://github.com/bats-core/bats-core): test framework\n- [Other shell projects](https://github.com/adoyle-h?tab=repositories\u0026q=\u0026type=source\u0026language=shell\u0026sort=stargazers) created by me.\n\n## References\n\n- [pure-bash-bible](https://github.com/dylanaraps/pure-bash-bible)\n- https://www.gnu.org/software/bash/manual/\n- http://mywiki.wooledge.org/BashFAQ\n\n## [Test](./docs/test.md)\n\n## Suggestion, Bug Reporting, Contributing\n\n**Before opening new Issue/Discussion/PR and posting any comments**, please read [./docs/CONTRIBUTING.md](./docs/CONTRIBUTING.md).\n\n## Copyright and License\n\nCopyright 2019-2024 ADoyle (adoyle.h@gmail.com). Some Rights Reserved.\nThe project is licensed under the **Apache License Version 2.0**.\n\nRead the [LICENSE][] file for the specific language governing permissions and limitations under the License.\n\nRead the [NOTICE][] file distributed with this work for additional information regarding copyright ownership.\n\n\n\u003c!-- Links --\u003e\n\n[LICENSE]: ./LICENSE\n[NOTICE]: ./NOTICE\n[tags]: https://github.com/adoyle-h/lobash/tags\n\n[module-usages]: ./docs/module-usages/README.md\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadoyle-h%2Flobash","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadoyle-h%2Flobash","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadoyle-h%2Flobash/lists"}