bash-tpl

Template for your bash projects with battery included !

Quickstart

to get started with this template, git clone this repo and push to a new origin. you can copy/paste the code below to do so :

printf "enter your repo url\n" \
  && read REPO_URL \
  && printf "enter your project name\n" \
  && read PROJECT_NAME \
  && git clone https://git.hvn.wf/repo-template/bash-tpl.git \
  && git -C bash-tpl remote set-url origin "${REPO_URL}" \
  && mv bash-tpl "${PROJECT_NAME}"

To get the most of the this template, i reccommend to set up a devcontainer environnement for VScode. You can do this easily with Devpod (https://devpod.sh/). you can copy/ below for a local configuration using podman as container engine. It will also create two shared directory on your home for container-storage and libpod, needed by the devcontaienr (see devcontainer.json) for more detail. Ensure that devpod-cli is installed and in your path before running this :

printf "enter local path to your git repo\n" \
&& read REPO_LOCAl_PATH \
&& mkdir -p "${HOME}"/.devcontainer-volumes/{container-storage,libpod} \
&& devpod provider add docker -o DOCKER_PATH=podman \
&& devpod up "${REPO_LOCAl_PATH]" --ide vscode

voila ! everything is set, you just have to run mise install in vscode terminal to install dev-tools in mise config.

Vscode extension will be automatically installed, check them out in the extension tab, or in the devcontainer.json.

How to

Dev-workflow

I develop programs following test diven devloppement methodology (https://en.wikipedia.org/wiki/Test_driven_development). I write test unit case in tests/unit_tests and then write function code in src/ to make my test case pass. When i'm done with the function. i write integration test case (same frammwork, but they run against the compiled artifact), then write main logic in main.sh. The artifact is builded by a setup step in my int_test code.

Env variables/secret

Env variable can be defined in mise.toml, or in the forge if you just need those variable in ci. Secrets are kept on the forge.

Automated tasks

to simplify usual task ( run tst, artifact building, setup thing) i am using mise tasks in dedicated file in .mise-tasks. There is 3 tasks by default :

• test : run bashunit test. You must specify the type of test. Available args are unit_tests,int_tests or all. you can also activate bashunit verbose with -v.
• build: build artifact. You must specify artifact name.
• symlink-prettier-plugin: symlink /root/.local/share/mise/installs/< plugin_name >/latest/lib/node_modules to ./node_module, so prettier plugin installed via mise could be usable in project directory

To run a task, type mise run <task_name> <args> <option/flag>

CI/CD

CI/CD pipelines are using forgejo action system (https://forgejo.org/docs/next/user/actions/overview/). The syntax is mstly similar to github action, so github action docs should apply in most case (https://github.com/features/actions). Maybe i will do a template for gitlab one day, stay tuned.

Linting/code formating

I use shellcheck to lint bash code. feel free to check .shelcheckrc, if i ever add an exception to shchelchek, there should be a comment explaining why.

To ensure my code is properly formated, i use Editorconfig (https://editorconfig.org/) and prettier (https://prettier.io/) with bash and toml plugin. Feel free to check .editorconfig and .prettierrc.yaml to see what i've defined.

I will add a step to format everything in my ci late, for now its just a check, i format things locally.

additional notes

this project is following the semantic versioning guidline (https://semver.org/),as well as Angular conventional commits (https://www.conventionalcommits.org/en/v1.0.0-beta.4/). Gitmojis are here for fun (https://gitmoji.dev/).

I am trying to stick to known best practice to the best of my abilities:

• https://bertvv.github.io/cheat-sheets/Bash.html

Watch out for new version of this repo, i am always learning !

Useful links

here some external documentation for all the tool used in this template:

• devcontainer: isolated dev environnement in container (https://containers.dev/)
• mise-en-place: swiss army knife for your projects (https://mise.jdx.dev/)
• bashunit: simple testing framwork built for bash (https://bashunit.typeddevs.com/)
• shellcheck: the bash linter (https://www.shellcheck.net/)
• git-chglog: generate your changelog from conventional commit (https://github.com/git-chglog/git-chglog)
• editorconfig: maitain your coding style from your ide (https://editorconfig.org/)
• prettier: an opinnionated code formatter (https://prettier.io/)
• Forgejo: light and efficient software forge (https://forgejo.org/)