<li>Copy the desired portions of <ahref="http://bash3boilerplate.sh/main.sh"><codeclass="language-plaintext highlighter-rouge">main.sh</code></a> into your own script.</li>
<li>Download <ahref="http://bash3boilerplate.sh/main.sh"><codeclass="language-plaintext highlighter-rouge">main.sh</code></a> and start pressing the delete-key to remove unwanted things</li>
<p>Once the <codeclass="language-plaintext highlighter-rouge">main.sh</code> has been tailor-made for your project, you can either append your own script in the same file, or source it in the following ways:</p>
<li>Copy <ahref="http://bash3boilerplate.sh/main.sh"><codeclass="language-plaintext highlighter-rouge">main.sh</code></a> into the same directory as your script and then edit and embed it into your script using Bash’s <codeclass="language-plaintext highlighter-rouge">source</code> include feature, e.g.:</li>
<li>Source <ahref="http://bash3boilerplate.sh/main.sh"><codeclass="language-plaintext highlighter-rouge">main.sh</code></a> in your script or at the command line:</li>
<li>Copy the line from the <codeclass="language-plaintext highlighter-rouge">main.sh</code><ahref="https://github.com/kvz/bash3boilerplate/blob/v2.1.0/main.sh#L109-L115">read block</a> that most resembles the desired behavior and paste the line into the same block.</li>
<li>Edit the single-character (e.g., <codeclass="language-plaintext highlighter-rouge">-d</code>) and, if present, the multi-character (e.g., <codeclass="language-plaintext highlighter-rouge">--debug</code>) versions of the flag in the copied line.</li>
<li>Omit the <codeclass="language-plaintext highlighter-rouge">[arg]</code> text in the copied line, if the desired flag takes no arguments.</li>
<li>Omit or edit the text after <codeclass="language-plaintext highlighter-rouge">Default=</code> to set or not set default values, respectively.</li>
<li>Omit the <codeclass="language-plaintext highlighter-rouge">Required.</code> text, if the flag is optional.</li>
<p>To find out the value of an argument, append the corresponding single-character flag to the text <codeclass="language-plaintext highlighter-rouge">$arg_</code>. For example, if the [read block]
<p>The <ahref="https://github.com/kvz/bash3boilerplate/blob/v2.1.0/main.sh#L26-L28">magic variables</a> in <codeclass="language-plaintext highlighter-rouge">main.sh</code> are special in that they have a different value, depending on your environment. You can use <codeclass="language-plaintext highlighter-rouge">${__file}</code> to get a reference to your current script, and <codeclass="language-plaintext highlighter-rouge">${__dir}</code> 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 <codeclass="language-plaintext highlighter-rouge">${__file}</code>, which is accessible via <codeclass="language-plaintext highlighter-rouge">${0}</code>, or the current directory of the administrator running the script, accessible via <codeclass="language-plaintext highlighter-rouge">$(pwd)</code>.</p>
<h2id="how-can-i-contribute-to-this-project">How can I contribute to this project?</h2>
<p>Please fork this repository. After that, create a branch containing your suggested changes and submit a pull request based on the master branch
of <ahref="https://github.com/kvz/bash3boilerplate/">https://github.com/kvz/bash3boilerplate/</a>. We are always more than happy to accept your contributions!</p>
<h2id="why-are-you-typing-bash-in-all-caps">Why are you typing BASH in all caps?</h2>
<p>As an acronym, Bash stands for Bourne-again shell, and is usually written with one uppercase.
This project’s name, however, is “BASH3 Boilerplate”. It is a reference to
“<ahref="https://html5boilerplate.com/">HTML5 Boilerplate</a>”, 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”.</p>
<h2id="how-can-i-locally-develop-and-preview-the-b3bp-website">How can I locally develop and preview the b3bp website?</h2>
<p>You should have a working Node.js >=10, Ruby >=2 and <ahref="https://yarnpkg.com">YARN</a> install on your workstation. When that is the case, you can run:</p>
<p>This will install and start all required services and automatically open a webbrowser that reloads as soon as you make any changes to the source.</p>
<p>Any changes should be proposed as PRs. Anything added to <codeclass="language-plaintext highlighter-rouge">master</code> is automatically deployed using a combination of GitHub Actions and Pages.</p>
<h2id="you-are-saying-you-are-portable-but-why-wont-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?</h2>
<p>When we say <em>portable</em>, 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.</p>
<p>We run automated tests to make sure that it will. Here is some proof for the following platforms:</p>
<p>We used to offer a magic <codeclass="language-plaintext highlighter-rouge">__os</code> variable, but we quickly <ahref="https://github.com/kvz/bash3boilerplate/issues/38">discovered</a> that it would be hard
<p>The set -o nounset line in <codeclass="language-plaintext highlighter-rouge">main.sh</code> causes error termination when an unset environment variables is detected as unbound. There are multiple ways to avoid this.</p>
<spanclass="nb">echo</span><spanclass="k">${</span><spanclass="nv">NAME1</span><spanclass="k">:-</span><spanclass="nv">Damian</span><spanclass="k">}</span><spanclass="c"># echos Damian, $NAME1 is still unset</span>
<spanclass="c"># method 2</span>
<spanclass="nb">echo</span><spanclass="k">${</span><spanclass="nv">NAME2</span>:<spanclass="p">=Damian</span><spanclass="k">}</span><spanclass="c"># echos Damian, $NAME2 is set to Damian</span>
<spanclass="c"># method 3</span>
<spanclass="nv">NAME3</span><spanclass="o">=</span><spanclass="k">${</span><spanclass="nv">NAME3</span><spanclass="k">:-</span><spanclass="nv">Damian</span><spanclass="k">}</span><spanclass="p">;</span><spanclass="nb">echo</span><spanclass="k">${</span><spanclass="nv">NAME3</span><spanclass="k">}</span><spanclass="c"># echos Damian, $NAME3 is set to Damian</span>
<p>This subject is briefly touched on as well in the <ahref="README.md#safety-and-portability">Safety and Portability section under point 5</a>. b3bp currently uses <ahref="https://github.com/kvz/bash3boilerplate/blob/v2.1.0/main.sh#L252">method 1</a> when we want to access a variable that could be undeclared, and <ahref="https://github.com/kvz/bash3boilerplate/blob/v2.1.0/main.sh#L31">method 3</a> when we also want to set a default to an undeclared variable, because we feel it is more readable than method 2. We feel <codeclass="language-plaintext highlighter-rouge">:=</code> is easily overlooked, and not very beginner friendly. Method 3 seems more explicit in that regard in our humble opinion.</p>
<h2id="how-can-i-detect-or-trap-ctrl-c-and-other-signals">How can I detect or trap Ctrl-C and other signals?</h2>
<p>You can trap <ahref="https://en.wikipedia.org/wiki/Unix_signal">Unix signals</a> like <ahref="https://en.wikipedia.org/wiki/Control-C">Ctrl-C</a> with code similar to:</p>
<divclass="language-bash highlighter-rouge"><divclass="highlight"><preclass="highlight"><code><spanclass="c"># trap ctrl-c and call ctrl_c()</span>
<p>The PID of a running script is contained in the <codeclass="language-plaintext highlighter-rouge">${$}</code> variable. This is <em>not</em> the pid of any subshells. With Bash 4 you can get the PID of your subshell with <codeclass="language-plaintext highlighter-rouge">${BASHPID}</code>. For a comprehensive list of Bash built in variables see, e.g., http://www.tldp.org/LDP/abs/html/internalvariables.html</p>
