diff --git a/docs/bin.md b/docs/bin.md index 319958d..1932661 100644 --- a/docs/bin.md +++ b/docs/bin.md @@ -1,14 +1,14 @@ # Bin -Various shell scripts that can be used as "binaries". +Various scripts that can be used as "binaries". --- ## backup A wrapper for `rsync`. -Backups source directory to a different filesystem (drive) as backing up on the same drive sort of defies the goal of backup. -In archive mode backups are compressed to save disk space. +Backups source directory to a different file system (drive) as backing up on the same drive sort of defies the goal of backup. +In archive mode, backups are compressed to save disk space. This compression is done by `pigz` which creates standard `gzip` files but spreads the work over multiple processors and cores when compressing so it can utilize modern hardware. Modes: diff --git a/docs/index.md b/docs/index.md index f74adce..f5197f6 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,16 +1,17 @@ # Introduction -Hi! :cowboy_hat_face: +Welcome! :cowboy_hat_face: Here you can find the documentation for [_ES-Progress Bash Library_](https://github.com/es-progress/shell){target=\_blank}. +It aims to provide comprehensive guidance on using this library. -This library consist of standalone shell scripts, called "binaries" (`bin/`) here :wink: and various shell functions (`lib/`). -Certain functions are useful for interactive use on the command-line, while others makes more sense sourced in scripts. +The library consists of standalone shell scripts, referred to as "binaries" (`bin/`) here :wink: and various shell functions (`lib/`). +Certain functions are designed for interactive use on the command-line, while others make more sense sourced in scripts. It was written with Bash in mind therefore portability was not a requirement. First, check the [Installation instructions](install.md). Though most of the "binaries" are intended for standalone use which you can simply download and run, -some of them use functions from the library ("lib") and bootstrapping may not be trivial. +some of them use functions from the function library (`lib/`) and bootstrapping may not be trivial and require additional setup. Then you can find the reference documentation for each script and function. diff --git a/docs/install.md b/docs/install.md index eed6d6c..00df0db 100644 --- a/docs/install.md +++ b/docs/install.md @@ -4,14 +4,14 @@ Library functions are organized by category into smaller files (`lib/*.sh`) so t Usually functions use each other, so this makes using them a bit harder as several files need to be sourced in order to define all functions. Yet it's possible to include only the lib files you need in a script, it's generally easier to load them all. -For this purpose there is a loader: (`lib/_loader.sh`). Just source this file and it will source all other libraries. +For this purpose there is a loader (`lib/_loader.sh`). Simply source this file, and it will automatically source all other libraries. In supplied scripts (`bin/`) loader is referenced by an environment variable (`ES_SHELL_LOADER`). It's recommended to use this env var in your scripts also. -For details on how to use loader check [Reference](lib/_loader.md). +For detailed instructions on using the loader check [Reference](lib/_loader.md). -## Installation steps +**Installation steps** 1. Clone this repo ``` diff --git a/docs/lib/_loader.md b/docs/lib/_loader.md index 6e8749c..d3039d5 100644 --- a/docs/lib/_loader.md +++ b/docs/lib/_loader.md @@ -1,7 +1,7 @@ # Loader -Helper to bootstrap libraries. This file sources all library files so functions will get defined and be available. -Basically you need to source this file in any script where you want to use library functions. +Helper to bootstrap libraries. This file sources all library files so functions will be defined and available. +Basically, you need to source this file in any script where you want to use library functions. **Usage in scripts** @@ -9,7 +9,7 @@ Basically you need to source this file in any script where you want to use libra # Source loader . /path/to/shell/lib/_loader.sh -# Or use the envvar (recommended for maintainabilty & portability) +# Or use the envvar (recommended for maintainability & portability) . "${ES_SHELL_LOADER}" # Now functions are defined diff --git a/docs/lib/analytics.md b/docs/lib/analytics.md index d447705..ddfdb71 100644 --- a/docs/lib/analytics.md +++ b/docs/lib/analytics.md @@ -6,8 +6,8 @@ Functions for statistics and analysis. ## anal-disk-usage -Analyze disk usage. Prints the disk space used by each sub-directory in any directory in ascending order. -Also reports how many percent each sub-directory's size takes up in total size. +Analyze disk usage. Displays the disk space used by each sub-directory in any directory in ascending order. +Additionally, it reports the percentage of total size occupied by each sub-directory. **Usage** diff --git a/docs/lib/certificate.md b/docs/lib/certificate.md index 00c01e9..2012166 100644 --- a/docs/lib/certificate.md +++ b/docs/lib/certificate.md @@ -1,10 +1,10 @@ # Certificate -Functions for managing X509 certificates & keys. Basically a wrapper for `openssl`. +Functions for managing X509 certificates & keys. Essentially, it serves as a wrapper for `openssl`. -With these functions you can setup your own Certificate Authority (CA) and issue X509 certificates on your behalf which is useful for TLS. +These functions offer a way to set up your own Certificate Authority (CA) and issue X509 certificates on your behalf which is useful for TLS (Transport Layer Security). Then only your Root CA certificate needs to be trusted by clients and all your issued certificates will be trusted too. -Probably it won't be trusted by anybody except you so it can't be used for public sites, but it's great for internal use and Dev/CI environments. +It may not be trusted by anyone except you. So it can't be used for public sites, but it's great for internal use and Dev/CI environments. --- diff --git a/docs/lib/db.md b/docs/lib/db.md index 6e23c33..bf40fe6 100644 --- a/docs/lib/db.md +++ b/docs/lib/db.md @@ -1,13 +1,13 @@ -# DataBase +# Database -Functions for MySQL databases. +Functions for managing MySQL databases, including data export, structure export, querying, and more. --- ## db-dump-data-db Dump full DB. Only data (each record on a separate row) is exported with no table structures. -This could be useful for debugging as it allows a readable diff for changes in data. +This can be valuable for debugging as it enables readable diffs for changes in data. **Usage** @@ -15,7 +15,7 @@ This could be useful for debugging as it allows a readable diff for changes in d db-dump-data-db DB [EXTRA]... Params: -DB DataBase name +DB Database name EXTRA Optional extra params to 'mysqldump' ``` @@ -32,7 +32,7 @@ This could be useful for debugging as it allows a readable diff for changes in d db-dump-data-tables DB TABLE... Params: -DB DataBase name +DB Database name TABLE Tables to export ``` @@ -48,7 +48,7 @@ Dump full DB (data in compact form + table structures). This could be used for b db-dump-full-db DB [EXTRA]... Params: -DB DataBase name +DB Database name EXTRA Optional extra params to 'mysqldump' ``` @@ -56,7 +56,7 @@ EXTRA Optional extra params to 'mysqldump' ## db-dump-full-tables -Dump specific tables from DB. Data (in compact form) and table structure is exported also. +Dump specific tables from DB. Data in compact form and table structure is exported also. **Usage** @@ -64,7 +64,7 @@ Dump specific tables from DB. Data (in compact form) and table structure is expo db-dump-full-tables DB TABLE... Params: -DB DataBase name +DB Database name TABLE Tables to export ``` @@ -80,7 +80,7 @@ Dump full DB structure. No data exported. db-dump-structure-db DB [EXTRA]... Params: -DB DataBase name +DB Database name EXTRA Optional extra params to 'mysqldump' ``` @@ -96,7 +96,7 @@ Dump specific table structures from DB. No data exported. db-dump-structure-tables DB TABLE... Params: -DB DataBase name +DB Database name TABLE Tables to export ``` @@ -112,14 +112,14 @@ Base wrapper for `mysqldump`. The other specific dumper functions add parameters db-dump-wrapper PARAMS... Params: -PARAMS Params to 'mysqldump' +PARAMS Parameters to 'mysqldump' ``` --- ## db-list-tables -List all tables in a DataBase, each table on a new line for easy further processing. +List all tables in a Database, each table on a new line for easy further processing. Tables can be filtered by pattern where SQL style wildcards are allowed. **Usage** @@ -128,7 +128,7 @@ Tables can be filtered by pattern where SQL style wildcards are allowed. db-list-tables DB PATTERN Params: -DB DataBase name +DB Database name PATTERN Pattern to filter tables. SQL wildcards are allowed, e.g. '%cache%'. ``` @@ -137,7 +137,7 @@ PATTERN Pattern to filter tables. ## db-query -Run single queries on a DataBase. +Execute single queries on a database. **Usage** @@ -145,7 +145,7 @@ Run single queries on a DataBase. db-query DB QUERY [EXTRA]... Params: -DB DataBase name +DB Database name QUERY Query to execute EXTRA Optional extra params to 'mysql' ``` @@ -155,7 +155,7 @@ EXTRA Optional extra params to 'mysql' ## db-replace Replace all occurences of a string in a Database table. This is basically an ETL (extract-transform-load) operation. -Table is dumped first, then `sed` substition and changed data imported finally. Import means dropping and recreating table with new data. +Table is dumped first, then `sed` substitution and changed data imported finally. Import means dropping and recreating table with new data. Basic Regular Expressions (BRE; no `-r` switch) is used for `sed` so `+`, `?,` and `(`, `)` treated literal. Delimiter for `sed` substition command can be changed as well, it defaults to `@` so strings can't contain `@` character. @@ -167,7 +167,7 @@ If your string contains that character you can select a different delimiter that db-replace DB TABLE SEARCH REPLACE [DELIMITER] Params: -DB DataBase name +DB Database name TABLE Table name SEARCH Search string REPLACE Replace string diff --git a/docs/lib/dev.md b/docs/lib/dev.md index c47a872..5db03fe 100644 --- a/docs/lib/dev.md +++ b/docs/lib/dev.md @@ -1,13 +1,13 @@ # Development Tools -Tools and utilities for development. +This section provides a range of utilities and functions to assist in the development process. --- ## build-mkdocs -Build an `mkdocs` site (like this one :smiley:). -Generated site's permission and group changed for serving through Apache (`www-data`). +Build an MkDocs site (like this one :smiley:). +The generated site's permissions and group are changed for serving through Apache (`www-data`). **Usage** @@ -24,8 +24,8 @@ EXTRA Optional extra params to 'mkdocs build' ## bump-version -Function to bump (increase by one) the version-number if semantic versioning is used. -If the major or minor version is bumped then the less important parts will be nulled as in common sense. +Function to increment (increase by one) the version-number if semantic versioning is used. +If the major or minor version is bumped then the less important parts will be reset. E.g. `1.2.3` becomes `2.0.0` after bumping major version. **Usage** @@ -75,7 +75,7 @@ REMOTE Remote host ## ppretty-php -Pretty-prints a serialized PHP object/array. Can accept serial string from stdin also so it's great to use in a pipe. +Pretty prints a serialized PHP object/array. Can accept serial string from stdin also so it's great to use in a pipe. **Usage** diff --git a/docs/lib/error.md b/docs/lib/error.md index 1043edd..c58b527 100644 --- a/docs/lib/error.md +++ b/docs/lib/error.md @@ -6,7 +6,7 @@ Functions for handling errors. ## Error codes -The following variables holds error codes that are exported so they can be used in other scripts as environment vars to indicate error causes. +The following variables contain error codes that are exported so they can be used in other scripts as environment vars to indicate error reasons. ``` _E_ABORT Program aborted diff --git a/docs/lib/files.md b/docs/lib/files.md index da870fd..d629b5c 100644 --- a/docs/lib/files.md +++ b/docs/lib/files.md @@ -6,7 +6,7 @@ Functions for managing files and querying the filesystem. ## dir-file -Get directory of a file. +Get the directory of a file. **Usage** @@ -21,7 +21,7 @@ FILE File to check ## dir-parents -Get all parent directory of a dir. By default return parents as a space separated string. +Get all parent directory of a dir. By default, return parents as a space-separated string. The separator character can be specified if whitespace contained dirs are a concern. **Usage** @@ -50,7 +50,7 @@ dir-script ## give -Recursively set group ownership and remove all world permissions on directories. +Recursively set group ownership and remove all world (public) permissions on directories. **Usage** diff --git a/docs/lib/git.md b/docs/lib/git.md index 87f7fae..2b1e973 100644 --- a/docs/lib/git.md +++ b/docs/lib/git.md @@ -18,7 +18,7 @@ ggit-adog ## ggit-base -Rebase source onto target and force-push rebased branch to remote. +Rebase source onto target and forcefully push rebased branch to the remote repository. **Usage** @@ -35,7 +35,7 @@ REMOTE Remote repository to pull and push. Defaults to 'origin'. ## ggit-diff -Show only a summarized diff: list changed files and number of changed lines. +Show a summarized difference: list changed files and the number of changed lines. **Usage** @@ -67,7 +67,7 @@ COMMITS Numer of commits to go back from HEAD ## ggit-merge -Merge source branch into target branch. This includes several steps: +Merge the source branch into the target branch (performs a fast-forward merge). This includes several steps: 1. Checkout _source_ branch and pull remote changes from remote repo 1. Checkout _target_ branch and pull remote changes from remote repo @@ -105,7 +105,7 @@ SHA Create patch from this commit specified by SHA ## ggit-pull -Pull local branch from remote. Also update submodules. +Pull the local branch from the remote repository, also updating any submodules. **Usage** diff --git a/docs/lib/github.md b/docs/lib/github.md index 11adc3c..d18ab00 100644 --- a/docs/lib/github.md +++ b/docs/lib/github.md @@ -74,7 +74,7 @@ ghub-issue REPO [EXTRA]... Params: REPO GitHub repository, given as "owner/repo-name". Default to repository in current working dir. -EXTRA Optional extra params to 'gh' +EXTRA Optional extra parameters to 'gh' ``` --- @@ -114,7 +114,7 @@ EXTRA Optional extra params to 'gh' ## ghub-pr -Create PR in browser for current repository (repo in working dir). +Create PR (pull request) in browser for current repository (repo in working dir). **Usage** @@ -163,7 +163,7 @@ EXTRA Optional extra params to 'gh' ## ghub-repo-template -Create new private repository from template repo. +Create new private repository from GitHub template repository. **Usage** @@ -231,7 +231,7 @@ EXTRA Optional extra params to 'gh' ## ghub-sync-labels -Sync labels from template repo to target repo. +Sync labels from template repository to target repository. Non-existent labels will be created, extra ones deleted, different ones updated to match template. After this operation labels will the same as the template. Matching is based on label name. diff --git a/docs/lib/network.md b/docs/lib/network.md index 3551218..8eceec9 100644 --- a/docs/lib/network.md +++ b/docs/lib/network.md @@ -23,9 +23,9 @@ SELECTOR DKIM selector ## iplocation Query [Ipstack](https://ipstack.com/){target=\_blank} for GeoIP data. -You need an Ipstack account and access key to query info. +You need an Ipstack account and an access key to query info. This function looks for this token in an environment variable: `IPSTACK_TOKEN`. -You can set this in your `.bashrc` or if you're generally not happy by providing credentials in env vars, you can give token just for this command: `IPSTACK_TOKEN=yourtoken iplocation 8.8.8.8`. +You can configure this in your `.bashrc` or if you're generally not happy by providing credentials in env vars, you can give token just for this command: `IPSTACK_TOKEN=yourtoken iplocation 8.8.8.8`. **Usage** diff --git a/docs/lib/process.md b/docs/lib/process.md index 040f86a..4356776 100644 --- a/docs/lib/process.md +++ b/docs/lib/process.md @@ -18,7 +18,7 @@ check-not-root ## check-root -Check if script is running as root. If not running as root print error and return with non-zero exit code. +Determine if script is running as root. If not running as root print error and return with non-zero exit code. **Usage** @@ -30,7 +30,7 @@ check-root ## command-exists -Check if command is available on the system. Return non-zero exit code if not available. +Verify if command is available on the system. Return non-zero exit code if the command is not available. **Usage** @@ -62,7 +62,7 @@ COMMAND Command to run ## foreach-subdir-pipe Run command in each sub directory of current working dir and pipe results to another command. -Commands are executed in a subshell so it will continue on errors and has no effects on current shell. +Commands are executed in a nested shell so it will continue on errors and has no effects on current shell. **Usage** diff --git a/docs/lib/ssh.md b/docs/lib/ssh.md index 5b2d6dc..fe20497 100644 --- a/docs/lib/ssh.md +++ b/docs/lib/ssh.md @@ -41,7 +41,7 @@ PORT Local port ## ssh-create-key Generate a new ed25519 SSH key-pair. -Key is saved in current directory and 96 rounds of hashing is done on the private key. +The key is saved in the current directory, and the private key undergoes 96 rounds of hashing **Usage** diff --git a/docs/lib/text.md b/docs/lib/text.md index 44af794..c7ca08d 100644 --- a/docs/lib/text.md +++ b/docs/lib/text.md @@ -6,7 +6,7 @@ Bash functions for text processing & strings. ## implode -Join arguments with a joining character as expected from other languages. +Concatenate arguments using a specified joining character, similar to how it's done in other programming languages. This can be useful to create e.g. comma-delimited list from an array of names. **Usage** diff --git a/docs/lib/ui.md b/docs/lib/ui.md index 7369874..cec4698 100644 --- a/docs/lib/ui.md +++ b/docs/lib/ui.md @@ -55,7 +55,7 @@ cls ## confirm Ask for confirmation. If reply is `y` or `Y` return with exit code "0" otherwise non-zero. -Prompt can be configured but I think the default "Are you sure?" covers most situations... :smiley: +You can configure the prompt, but the default 'Are you sure?' should suffice for most situations. :smiley: **Usage** diff --git a/docs/nav.md b/docs/nav.md index aa77b16..0b2e6f5 100644 --- a/docs/nav.md +++ b/docs/nav.md @@ -5,7 +5,7 @@ - Lib - [Analytics](lib/analytics.md) - [Certificates](lib/certificate.md) - - [DataBase](lib/db.md) + - [Database](lib/db.md) - [Dev Tools](lib/dev.md) - [Error Handling](lib/error.md) - [Files](lib/files.md)