bashsmith

A template for smithing Bash scripts.

https://github.com/bkuhlmann/bashsmith

Keywords

Repository

A template for smithing Bash scripts.

README.adoc

:toc: macro
:toclevels: 5
:figure-caption!:

= Bashsmith

Bashsmith is a project template for smithing new link:https://www.gnu.org/software/bash[Bash]
shell-based projects based on best practices. This project is meant to be cloned and customized for
your specific shell scripting needs giving you a foundation from which to get started faster than
with an empty slate.

toc::[]

== Features

* Provides default project structure for creating new Bash projects.
* Provides default settings for making Bash scripts easier to develop and debug.

== Requirements

* link:https://www.gnu.org/software/bash[Bash]

== Setup

To install, run:

[source,bash]
----
git clone https://github.com/bkuhlmann/bashsmith.git
cd bashsmith
git checkout 6.7.0
----

== Usage

=== File Structure

All files located within this project provide the basic structure/blueprint for creating new Bash
script projects. The structure is organized as follows:

....
├── CHANGES.adoc          # The details of past version releases.
├── CODE_OF_CONDUCT.adoc  # Guidelines for encouraging harassment-free contributions.
├── CONTRIBUTING.adoc     # The details of how to contribute to the project.
├── LICENSE.adoc          # The license and copyright legalities of the project.
├── README.adoc           # The project overview, setup, usage, testing, etc.
├── bin                   # A folder for executable Bash scripts.
│   └── run               # The main run script (which loads the lib and settings).
├── lib                   # A folder for Bash functions and custom code.
│   └── cli.sh            # Provides CLI prompt options for the main `run` script.
├── settings              # The global/project settings for easy manipulation/tweaking.
│   └── main.sh           # The global settings (set with safe defaults).
....

=== Template

The following documents what each template option is:

[source,bash]
----
# Exit, with error message, when attempting to use an undefined variable.
# Alias: `set -u`.
set -o nounset

# Abort script at first error when a command exits with non-zero status.
# Alias: `set -e`.
set -o errexit

# Return exit status of the last command in the pipe that returned a non-zero return value.
set -o pipefail

# Defines newlines and tabs as delimiters for splitting words and iterating arrays.
IFS=$'\n\t'
----

=== Debugging

For debugging purposes, you can add the following option:

[source,bash]
----
# Prints all executed commands.
# Alias: `set -x`.
set -o xtrace
----

The above is useful for debugging purposes but probably not something you want always enabled.

💡 For additional options, use `help set` to learn more.

== Development

To contribute, run:

[source,bash]
----
git clone https://github.com/bkuhlmann/bashsmith.git
cd bashsmith
----

== Tests

Consider using link:https://github.com/sstephenson/bats[Bats].

== link:https://alchemists.io/policies/license[License]

== link:https://alchemists.io/policies/security[Security]

== link:https://alchemists.io/policies/code_of_conduct[Code of Conduct]

== link:https://alchemists.io/policies/contributions[Contributions]

== link:https://alchemists.io/policies/developer_certificate_of_origin[Developer Certificate of Origin]

== link:https://alchemists.io/projects/bashsmith/versions[Versions]

== link:https://alchemists.io/community[Community]

== Credits

Engineered by link:https://alchemists.io/team/brooke_kuhlmann[Brooke Kuhlmann].

Owner

Citation (CITATION.cff)

cff-version: 1.2.0
message: Please use the following metadata when citing this project in your work.
title: Bashsmith
abstract: A template for smithing Bash scripts.
version: 6.7.0
license: Hippocratic-2.1
date-released: 2025-07-15
authors:
  - family-names: Kuhlmann
    given-names: Brooke
    affiliation: Alchemists
    orcid: https://orcid.org/0000-0002-5810-6268
keywords:
 - bash
 - shell
 - scripts
 - generator
 - templates
 - best practices
repository-code: https://github.com/bkuhlmann/bashsmith
repository-artifact: https://alchemists.io/projects/bashsmith
url: https://alchemists.io/projects/bashsmith

GitHub Events

Issues and Pull Requests

Last synced: 10 months ago