{"id":19592751,"url":"https://github.com/norbertkiszka/lib-bash","last_synced_at":"2025-11-21T12:04:04.760Z","repository":{"id":232123566,"uuid":"783507057","full_name":"norbertkiszka/lib-bash","owner":"norbertkiszka","description":"Bash functions library: ansi colors, version checker, whiptail menu wrapper, error handling, call trace, traps, system, chroot, git and more.","archived":false,"fork":false,"pushed_at":"2025-02-16T12:40:25.000Z","size":103,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-26T14:15:49.794Z","etag":null,"topics":["bash","bash-error-checking","bash-hacks","bash-script","bash-scripting","chroot-script","error-handling","lib-bash","libbash","library","scripts-collection","system-administration","whiptail-menu"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/norbertkiszka.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","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":{"github":"norbertkiszka"}},"created_at":"2024-04-08T03:02:48.000Z","updated_at":"2025-02-16T12:17:22.000Z","dependencies_parsed_at":"2024-11-11T08:38:38.502Z","dependency_job_id":"ce427468-7fed-41df-bf65-5f25cba7ff02","html_url":"https://github.com/norbertkiszka/lib-bash","commit_stats":null,"previous_names":["norbertkiszka/lib-bash"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/norbertkiszka/lib-bash","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/norbertkiszka%2Flib-bash","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/norbertkiszka%2Flib-bash/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/norbertkiszka%2Flib-bash/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/norbertkiszka%2Flib-bash/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/norbertkiszka","download_url":"https://codeload.github.com/norbertkiszka/lib-bash/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/norbertkiszka%2Flib-bash/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":285611835,"owners_count":27201484,"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","status":"online","status_checked_at":"2025-11-21T02:00:06.175Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["bash","bash-error-checking","bash-hacks","bash-script","bash-scripting","chroot-script","error-handling","lib-bash","libbash","library","scripts-collection","system-administration","whiptail-menu"],"created_at":"2024-11-11T08:36:54.668Z","updated_at":"2025-11-21T12:04:04.732Z","avatar_url":"https://github.com/norbertkiszka.png","language":"Shell","readme":"## What is this?\n\nThis is a bash library primarily intented for a project Orange Rigol at https://github.com/norbertkiszka/rigol-orangerigol-build\n\nBut... \u003cb\u003eshould be usable for many other projects with bash scripts\u003c/b\u003e.\n\nAlso it can be used directly straight from the terminal to help with administration tasks.\n\n## Features in short\n\n- Colors.\n- Version checker.\n- Whiptail menu helper.\n- Error handling by calling functions with colorized output.\n- Script and function call trace.\n- Exit and int signal traps.\n- System functions.\n- Chroot with mounts and unmounting (also after error).\n- Adding own traps for different situations (see public function list below).\n- Possibility to use it directly from a terminal ($ source /path/to/lib-bash.sh) instead of from script.\n- After being called directly, it can be recalled by a some script (it shouldnt trigger any problems).\n\n## Usage - include in script\nAdd `lib-bash.sh` to your script:\n```bash\nsource \"/path/to/lib-bash.sh\"\n```\n## Usage - inside terminal with interactive bash (not in script)\nYou can call it directly (from interactive bash instead from a script) and after that, You can call functions in this lib just by typing them like a in a script.\n\nFirst and simpliest method to do this:\n```bash\nsource \"/path/to/lib-bash.sh\" # it will detect direct call and it will not call exit when error function is executed (kinda ugly behaviour)\n```\nInstead of calling it everytime, Yoy can add this line into ~/.bashrc or into ~/.profile file.\n\nOther method possible from v0.1.2 which will behave more like in a real script. At first copy paste this code into terminal (not into script):\n```bash\nwhile true\ndo\n  bash # nested bash\ndone\n```\nFrom now any bash exit will cause to go back to loop in previous bash which will execute another bash.\n\nAfter that You can type this:\n```bash\nsource \"/path/to/lib-bash.sh\" libignoredirect # it will ignore direct call and it will behave same as included from script\n```\nIn that way, call to exit from this lib will cause to kill nested bash and return to previous bash which will execute another bash in a loop, instead of closing terminal emulator or using return when no arg ignoredirect is given.\n\nAfter each error You have to execute last line (source...) again because we are in another bash.\n\nUgly workaround of this is to add this line into ~/.bashrc - but still You have to copy this loop into terminal (and press enter ofc).\n\nThis currently cannot be scripted due to another bash behaviour in interactive mode - at least as far I know.\n\n## Public functions list, description and usage\n\nList below describes functions in order as its defined by this lib.\n\nSide note: Not all functions arguments are documented. See source code if not sure.\n\nGeneral:\n- version_is_eqal_or_greater_than  \n\t\u003cpre\u003e  Will return 1 when true, 0 otherwise.\n\t\n    Example:\u003c/pre\u003e\n\t```bash\n\tREQUIRED_BASH_VERSION=\"5.1\"\n\tif ! version_is_eqal_or_greater_than \"${BASH_VERSION}\" \"${REQUIRED_BASH_VERSION}\" ; then\n\t\terror \"Bash is older than ${REQUIRED_BASH_VERSION}. We will do cleanup and exit now, since we called error() function.\"\n\tfi\n\tinfo \"Continuing...\"\n\tdo_something\n\tMESSAGE=\"Script successfully finished doing something.\"\n\tsuccess $MESSAGE # Print success on stdout.\n\tsuccess_whiptail $MESSAGE # Print success in green whiptail window (msgbox).\n\t```\nColors:\n- echo_green, echo_red, echo_yellow, echo_white  \n\t\u003cpre\u003e  Colorized echo.\u003c/pre\u003e\n- echo_green_e, echo_red_e, echo_yellow_e, echo_white_e  \n\t\u003cpre\u003e  Colorized echo with interpretation of backslash escapes (same as echo -e).\u003c/pre\u003e\n\nError handling and debugging:\n- sctrace  \n\t\u003cpre\u003e  Trace of process execution tree.\u003c/pre\u003e\n- show_stacktrace_for_warnings\n\t\u003cpre\u003e  Will force to display (execute) stacktrace as normally only in error and error_e.\u003c/pre\u003e\n- always_show_stacktrace_at_exit\n\t\u003cpre\u003e  Display (execute) stacktrace always when exit is trapped.\u003c/pre\u003e\n- forbidden_warning  \n\t\u003cpre\u003e  Warning will trigger error (like in a gcc with -Werror).\u003c/pre\u003e\n- forbidden_warning_disable  \n\t\u003cpre\u003e  Warning will not trigger error.\u003c/pre\u003e\n- check_require_args_with_real_data  \n\t\u003cpre\u003e  Function helper to require arg(s).\u003c/pre\u003e\n- is_executable  \n\t\u003cpre\u003e  Check if given command is executable by bash.\n\t\n    It will check only first arg, since only first arg is a command and remaining args are args...\u003c/pre\u003e\n- require_executable  \n\t\u003cpre\u003e  Helper for functions that require (first) arg to be executable by bash (uses is_executable())\n\t\n    It will check only first arg, since first arg is a command and remaining args are args...\u003c/pre\u003e\n- info, notice, warning, error_without_exit, error, success, success_whiptail  \n\t\u003cpre\u003e  Self explanatory.\n\t\n    error function will trigger exit 1 unless lib was called directly from a terminal (bash interactive mode) and without libignoredirect passed as first arg.\n    \n    Any call to exit is catched by this lib and any exit code different than 0 will trigger debug output.\u003c/pre\u003e\n- info_e, notice_e, warning_e, error_without_exit_e, error_e, success_e, success_whiptail_e  \n\t\u003cpre\u003e  _e -  interpretation of backslash escapes (same as echo -e).\u003c/pre\u003e\n- errorhandling_use_whiptail_for_warning, errorhandling_use_whiptail_for_error  \n\t\u003cpre\u003e  Will force warning, warning_e, error and error_e to additionally show same message by whiptail\n- whiptail_display_warning  \u003c/pre\u003e\n\t\u003cpre\u003e  Display warning only by whiptail... And nothing more than just that.\n\t\n    It will return after displaying whiptail msgbox.\n    \n    Used internally, but it can be used outside of this lib.\u003c/pre\u003e\n- whiptail_display_error  \n\t\u003cpre\u003e  Display error only by whiptail... And nothing more than just that.\n\t\n    It will return after displaying whiptail msgbox.\n    \n    Used internally, but it can be used outside of this lib.\u003c/pre\u003e\n\nTraps:\n- trap_exit_at_first  \n\t\u003cpre\u003e  Add function to trap exit at first (both on exit success and on exit error).\u003c/pre\u003e\n- trap_exit_at_end  \n\t\u003cpre\u003e  Add trap function at exit and at very end.\u003c/pre\u003e\n- trap_exit_at_ok  \n\t\u003cpre\u003e  Add trap function at exit and when exit code is 0 (exit success).\u003c/pre\u003e\n- trap_exit_at_error  \n\t\u003cpre\u003e  Add trap function at exit and when exit code is not 0.\u003c/pre\u003e\n\nDebugging:\n- scriptstacktrace  \n\t\u003cpre\u003e  Display (via echo) script and function call stack.\u003c/pre\u003e\n\nSystem:\n- random_hex  \n\t\u003cpre\u003e  Generate random hex chars.\n    \n    Arg1: optional chars count. When omitted, it will generate 32 chars.\u003c/pre\u003e\n- sys_mktempdir  \n\t\u003cpre\u003e  Create and test temp directory. It will return path via echo.\n    \n    This directory will be automatically deleted at script exit - also in case of a error.\u003c/pre\u003e\n- sys_require_dev_null, sys_require_dev_zero, sys_require_dev_urandom, sys_require_tmp  \n\t\u003cpre\u003e  If given device or tmp doesnt exist it will generate error. It will also check if those files are \"real\" null/zero/etc.\u003c/pre\u003e\n- sys_chroot_add_bind  \n\t\u003cpre\u003e  Add directory to bind at every sys_chroot call.\n    \n    This directories will be unmounted at chroot command exit and at error.\n    \n    If destination path doesnt exists, it will be created.\n    \n    Arg1: source path.\n    Arg2: optional destination path - relative to chroot directory. If omitted, source path will be also used as a destination path.\u003c/pre\u003e\n- sys_chroot  \n\t\u003cpre\u003e  Chroot with mounted /proc, /sys, /dev, /dev/pts and optional binds added via sys_chroot_add_bind.\n    \n    Everything will be unmounted at exit and at error.\n    \n    Arg1: destination path.\n    Arg2: command.\n    Argn: optional args for a given command.\u003c/pre\u003e\n- scriptstacktrace  \n\t\u003cpre\u003e  Display (via echo) script and function call stack.\u003c/pre\u003e\n\nWhiptail menu helper:\n- whiptail_menu_reset  \n\t\u003cpre\u003e  Reset all options and settings.\n\t\n    Normally is no need to call it, since its being called everytime in function whiptail_menu_execute.\u003c/pre\u003e\n- whiptail_menu_set_height  \n\t\u003cpre\u003e  Set different menubox height than default. Only for next whiptail_menu_execute.\n\t\n    This option is one time - its reset to default after each whiptail_menu_execute() call.\n    \n    See: whiptail_menu_set_default_height, whiptail_menu_set_default_dimensions\u003c/pre\u003e\n- whiptail_menu_set_width  \n\t\u003cpre\u003e  Set different menubox width than default. Only for next whiptail_menu_execute.\n\t\n    This option is one time - its reset to default after each whiptail_menu_execute() call.\n    \n    See: whiptail_menu_set_default_width, whiptail_menu_set_default_dimensions\u003c/pre\u003e\n- whiptail_menu_set_list_height  \n\t\u003cpre\u003e  Set different menubox list height than default. Only for next whiptail_menu_execute.\n\t\n    This option is one time - its reset to default after each whiptail_menu_execute() call.\n    \n    See: whiptail_menu_set_default_list_height, whiptail_menu_set_default_dimensions\u003c/pre\u003e\n- whiptail_menu_set_dimensions  \n\t\u003cpre\u003e  Arg1: height (optional, give a empty string to pass).\n    Arg2: width (optional, give a empty string to pass).\n    Arg3: list height (optional, give a empty string to pass).\n    \n    See: whiptail_menu_set_default_dimensions\u003c/pre\u003e\n- whiptail_menu_set_default_height, whiptail_menu_set_default_width, whiptail_menu_set_default_list_height\n\t\u003cpre\u003e  Self explanatory.\u003c/pre\u003e\n- whiptail_menu_set_default_dimensions  \n\t\u003cpre\u003e  Set default dimensions.\n    Arg1: height (optional, give a empty string to pass).\n    Arg2: width (optional, give a empty string to pass).\n    Arg3: list height (optional, give a empty string to pass).\n    \n    See: whiptail_menu_set_default_dimension, whiptail_menu_set_default_height, whiptail_menu_set_default_width, whiptail_menu_set_default_list_height\u003c/pre\u003e\n- whiptail_menu_dont_add_dot_in_key  \n\t\u003cpre\u003e  Force to not add dot in option ids.\n\t\n    Those dots are only for displaying - it will be removed from WHIPTAIL_MENU_OPTION_ID by whiptail_menu_execute.\n\t\n    This option is one time - its reset to default (display dot) after each whiptail_menu_execute() call.\u003c/pre\u003e\n- whiptail_menu_title_set_prefix  \n\t\u003cpre\u003e  Set prefix for titles in every whiptail_menu_execute calls (it will not be reset by whiptail_menu_reset).\u003c/pre\u003e\n- whiptail_menu_set_backtitle  \n\t\u003cpre\u003e  Set backtitle for next whiptail_menu_execute call.\u003c/pre\u003e\n- whiptail_menu_set_default_backtitle, whiptail_menu_is_option_id_exist  \n\t\u003cpre\u003e  Self explanatory.\u003c/pre\u003e\n- whiptail_menu_set_default_item  \n\t\u003cpre\u003e  User will see selected this option id.\n\t\n    Option should be previously added by using whiptail_menu_option_add(), otherwise it will generate warning.\n    \n    See: warning, forbidden_warning\u003c/pre\u003e\n- whiptail_menu_option_add  \n\t\u003cpre\u003e  Add option to display.\n\t\n    Arg1: numeric id. It can be any integer without any order and is not required to start with any special number.\n    Arg2: text with displayed option\u003c/pre\u003e\n- whiptail_menu_add_option, whiptail_menu_options_add  \n\t\u003cpre\u003e  Alias for a whiptail_menu_option_add.\u003c/pre\u003e\n- whiptail_menu_execute  \n\t\u003cpre\u003e  Display whiptail (execute whiptail) to user.\n\t\n    Selected option id is saved to a var WHIPTAIL_MENU_OPTION_ID without dot (see whiptail_menu_dont_add_dot_in_key).\n\t\n    Selected option name is saved into a var WHIPTAIL_MENU_OPTION_NAME.\n    \n    If not sure how to use it, see tests/test-whiptail-menu.sh\u003c/pre\u003e\n\nGit:\n- git_last_commit_hash_short  \n\t\u003cpre\u003e  Get last commit short hash.\n\t\n    Arg1: optional directory. If not given, current directory will be used.\u003c/pre\u003e\n- git_list_modified_files  \n\t\u003cpre\u003e  Get list of modified files since last commit.\n\t\n    Arg1: optional directory. If not given, current directory will be used.\u003c/pre\u003e\n","funding_links":["https://github.com/sponsors/norbertkiszka"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnorbertkiszka%2Flib-bash","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnorbertkiszka%2Flib-bash","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnorbertkiszka%2Flib-bash/lists"}