Skip to content

check-shell-task.md

Latest commit

 

History

History
152 lines (96 loc) · 5.42 KB

check-shell-task.md

File metadata and controls

152 lines (96 loc) · 5.42 KB

"Check Shell Scripts" workflow (Task)

Check the repository's shell scripts for problems:

  • Static analysis using ShellCheck.
  • Formatting using shfmt.
  • Forgotten executable script file permissions.

This is the version of the workflow for projects using the Task task runner tool.

Installation

Workflow

Install the check-shell-task.yml GitHub Actions workflow to .github/workflows/

Assets

The formatting style defined in .editorconfig is the official standardized style to be used in all Arduino tooling projects and should not be modified.

Dependencies

The tool dependencies of this workflow are managed by Go.

If the project does not already have a go.mod file, install Go and then run the following command:

go mod init <module path>

(where <module path> is the URL of the project repository without the scheme e.g., github.com/foo/bar)

Add the tool dependencies by running the following command:

go get -tool github.com/go-task/task/v3/cmd/task@v3.44.1

Commit the resulting changes to the go.mod and go.sum files.

Configuration

Configure the paths of the shell scripts to be checked as elements in the job matrices of check-shell-task.yml at:

  • jobs.lint.strategy.matrix.script[]
  • jobs.formatting.strategy.matrix.script[]
  • jobs.executable.strategy.matrix.script[]

Example:

matrix:
  script:
    - path/to/some-script.sh
    - path/to/another-script.sh

Paths filters

The workflow is configured to be triggered on changes to any files in the repository that have a .sh or .bash file extension. If the project contains shell scripts without a file extension, the path to those scripts must be added to the following keys in check-shell-task.yml:

  • on.push.paths[]
  • on.pull_request.paths[]

Readme badge

Markdown badge:

[![Check Shell Scripts status](https://github.com/TODO_REPO_OWNER/TODO_REPO_NAME/actions/workflows/check-shell-task.yml/badge.svg)](https://github.com/TODO_REPO_OWNER/TODO_REPO_NAME/actions/workflows/check-shell-task.yml)

Replace the TODO_REPO_OWNER and TODO_REPO_NAME placeholders in the URLs with the final repository owner and name (example).

Asciidoc badge:

image:https://github.com/{repository-owner}/{repository-name}/actions/workflows/check-shell-task.yml/badge.svg["Check Shell Scripts status", link="https://github.com/{repository-owner}/{repository-name}/actions/workflows/check-shell-task.yml"]

Define the {repository-owner} and {repository-name} attributes and use them throughout the readme (example).

Commit message

Add infrastructure to check for problems with shell scripts

Tasks are provided to facilitate the development of the project's shell scripts:

- Detect common problems using ShellCheck.
- Format using shfmt.
- Check for forgotten executable script file permissions.

A GitHub Actions workflow is included to automatically run the tasks. The workflow is triggered on any push or pull that
changes relevant project files, in order to avoid the introduction of problems with the project filesystem. It is also
triggered periodically, in order to catch breakage caused by external changes.

PR message

Tasks are provided to facilitate the development of the project's shell scripts:

- Detect common problems using [**ShellCheck**](https://github.com/koalaman/shellcheck).
- Format using [**shfmt**](https://github.com/mvdan/sh).
- Check for forgotten executable script file permissions.

A GitHub Actions workflow is included to automatically run the tasks. The workflow is triggered on any push or pull that changes relevant project files, in order to avoid the introduction of problems with the project filesystem. It is also triggered periodically, in order to catch breakage caused by external changes.

Usage

In addition to the automated checks provided by the GitHub Actions workflow, the tasks can be ran locally.

Prerequisites

The following development tools must be available in your local environment:

  • ShellCheck - shell script static analysis tool.
  • shfmt - shell script formatting tool.
  • Task task runner tool.

Run static analysis

task shell:check SCRIPT_PATH="<script path>"

(where <script path> is the path to the script file)

Check file permissions

task shell:check-mode SCRIPT_PATH="<script path>"

(where <script path> is the path to the script file)

Format script

task shell:format SCRIPT_PATH="<script path>"

(where <script path> is the path to the script file)