ExternalVendorCode/bash3boilerplate
1
0
Fork 0
mirror of https://github.com/kvz/bash3boilerplate.git synced 2025-01-11 15:02:36 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Not completely done yet either

Browse Source
This commit is contained in:
AJvanLoon 2016-06-25 04:04:18 +02:00 committed by GitHub
parent c1f7354a7f
commit 2c9175dd50
1 changed files with 25 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

50
FAQ.md
View File

@ -22,7 +22,7 @@ A 'cli' is a [command-line interface](https://en.wikipedia.org/wiki/Command-line
## How do I incorporate BASH3 Boilerplate into my own project?
You can incorporate BASH3 Boilerplate into your project one of three ways:
You can incorporate BASH3 Boilerplate into your project in one of three ways:
1. Copy the desired portions of [main.sh](https://github.com/kvz/bash3boilerplate/blob/master/main.sh) into your own script.
1. Download [main.sh](https://github.com/kvz/bash3boilerplate/blob/master/main.sh) and start pressing the delete-key for unwanted things
@ -43,13 +43,13 @@ Once the `main.sh` has been tailor-made for your project you could either append
1. Copy the line the main.sh [read block](https://github.com/kvz/bash3boilerplate/blob/master/main.sh#L53) that most resembles the desired behavior and paste the line into the same block.
1. Edit the single-character (e.g., -d) and, if present, the multi-character (e.g., --debug) versions of the flag in the copied line.
1. Omit the "[arg]" text in the copied line if the desired flag takes no arguments.
1. Omit the "[arg]" text in the copied line, if the desired flag takes no arguments.
1. Omit or edit the text after "Default:" to set or not set default values, respectively.
1. Omit the "Required." text if the flag is optional.
1. Omit the "Required." text, if the flag is optional.
## How do I access the value of a command-line argument?
To evaluate the value of an argument, append the corresponding single-character flag to the text `$arg_`. For example, if the [read block]
To find out the value of an argument, append the corresponding single-character flag to the text `$arg_`. For example, if the [read block]
contains the line
```bash
-t --temp [arg] Location of tempfile. Default="/tmp/bar"
@ -63,7 +63,7 @@ __temp_file_name="${arg_t}"
## What is a magic variable?
The [magic variables](https://github.com/kvz/bash3boilerplate/blob/master/main.sh#L63) in `main.sh` are special in that they have a different value, depending on your environment. You can use `${__file}` to get a reference to your current script, `${__dir}` to get a reference to the directory it lives in. This is not to be confused with the location of the calling script that might be sourcing the `${__file}`, which is accessible via `${0}`, and the current directory of the administrator running the script, accessible via `$(pwd)`.
The [magic variables](https://github.com/kvz/bash3boilerplate/blob/master/main.sh#L63) in `main.sh` are special in that they have a different value, depending on your environment. You can use `${__file}` to get a reference to your current script, and `${__dir}` to get a reference to the directory it lives in. This is not to be confused with the location of the calling script that might be sourcing the `${__file}`, which is accessible via `${0}`, or the current directory of the administrator running the script, accessible via `$(pwd)`.
## How do I submit an issue report?
@ -71,20 +71,20 @@ Please visit our [Issues](https://github.com/kvz/bash3boilerplate/issues) page.
## How can I contribute to this project?
Please fork this repository. Then create a branch containing your suggested changes and submit a pull request based on the master branch
of <https://github.com/kvz/bash3boilerplate/>. We're a welcoming bunch, happy to accept your contributions!
Please fork this repository. After that, create a branch containing your suggested changes and submit a pull request based on the master branch
of <https://github.com/kvz/bash3boilerplate/>. We are always more than happy to accept your contributions!
## Why are you typing BASH in all caps?
As an acronym, Bash stands for Bourne-again shell, and is usually written with one uppercase.
This project's name however is "BASH3 Boilerplate" as a reference to
This project's name, however, is "BASH3 Boilerplate". It is a reference to
"[HTML5 Boilerplate](https://html5boilerplate.com/)", which was founded to serve a similar purpose,
only for crafting webpages.
Somewhat inconsistent but true to Unix ancestry, the abbreviation for our project is "b3bp".
Somewhat inconsistent – but true to Unix ancestry – the abbreviation for our project is "b3bp".
## How can I locally develop and preview the b3bp website?
You should have a working Node.js >=10 and Ruby >=2 install on your workstation. Afterwards, you can run:
You should have a working Node.js >=10 and Ruby >=2 install on your workstation. When that is the case, you can run:
```bash
npm run web:preview
@ -94,36 +94,36 @@ This will install and start all required services and automatically open a webbr
The source mainly consists of:
- `./README.md` Front page
- `./FAQ.md` FAQ page
- `./CHANGELOG.md` Changelog page
- `./website/_layouts/default.html` Design in which all pages are rendered
- `./website/public/app.js` Main JS file
- `./website/public/style.css` Main CSS file
- `./README.md` (Front page)
- `./FAQ.md` (FAQ page)
- `./CHANGELOG.md` (changelog page)
- `./website/_layouts/default.html` (the design in which all pages are rendered)
- `./website/public/app.js` (main JS file)
- `./website/public/style.css` (main CSS file)
The rest is dark magic you should probably steer clear from : )
The rest is dark magic from which you should probably steer clear. : )
Any changes should be proposed as PRs. Anything added to `master` is automatically deployed using a combination of Travis CI and GitHub Pages.
## You're saying you are portable - why won't b3bp code run in dash / busybox / posh / ksh / mksh / zsh?
## You are saying you are portable, but why won't b3bp code run in dash / busybox / posh / ksh / mksh / zsh?
When we say _portable_, we mean across Bash versions. Bash is widespread and most systems
offer at least version 3 of it. Make sure you have that available, and b3bp will work for you.
offer at least version 3 of it. Make sure you have that available and b3bp will work for you.
We run automated tests to make sure that it will, here's proof for the following platforms:
We run automated tests to make sure that it will. Here is some proof for the following platforms:
- [Linux](https://travis-ci.org/kvz/bash3boilerplate/jobs/109804166#L91) `GNU bash, version 4.2.25(1)-release (x86_64-pc-linux-gnu)`
- [OSX](https://travis-ci.org/kvz/bash3boilerplate/jobs/109804167#L2453) `GNU bash, version 3.2.51(1)-release (x86_64-apple-darwin13)`
This portability however does not mean we try to be compatible with
KornShell, Zsh, posh, yash, dash or other shells. We allow syntax that would explode if
This portability, however, does not mean that we try to be compatible with
KornShell, Zsh, posh, yash, dash, or other shells. We allow syntax that would explode if
you pasted it in anything but Bash 3 and up.
## How do I do Operating System detection?
We used to offer a magic `__os` variable, but quickly [discovered](https://github.com/kvz/bash3boilerplate/issues/38) that it would be hard
to create a satisfactory abstraction that is correct, covers enough use-cases,
and still has a relatively small footprint in `main.sh`.
We used to offer a magic `__os` variable, but we quickly [discovered](https://github.com/kvz/bash3boilerplate/issues/38) that it would be hard
to create a satisfactory abstraction that is not only correct, but also covers enough use-cases,
while still having a relatively small footprint in `main.sh`.
For simple OS detection, we recommend using the `${OSTYPE}` variable available in Bash as
is demoed in [this stackoverflow post](http://stackoverflow.com/a/8597411/151666):