Improve documentation examples and update feature showcase 📷

README.md

@@ -53,7 +53,7 @@ To evaluate results, Differential ShellCheck uses utilities `csdiff` and `csgrep
 * Colored console output with emojis
 * [SARIF support](https://docs.github.com/en/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning) - warnings are visible in the `Changed files` tab of the Pull-Request and as [comment alerts on Pull-Requests](https://github.blog/changelog/2022-06-02-users-can-view-and-comment-on-code-scanning-alerts-on-the-conversation-tab-in-a-pull-request/)
 * Ability to run in a verbose mode when run with [debug option](https://github.blog/changelog/2022-05-24-github-actions-re-run-jobs-with-debug-logging/)
-* Results displayed as [job summaries](https://github.blog/2022-05-09-supercharging-github-actions-with-job-summaries/)
+* Results displayed as [Job Summaries](https://github.blog/2022-05-09-supercharging-github-actions-with-job-summaries/) - [example](docs/images/job-summary-light.png)
 * Ability to configure Differential ShellCheck using [`.shellcheckrc`](https://github.com/koalaman/shellcheck/blob/master/shellcheck.1.md#rc-files)
 
 ## Usage
@@ -85,7 +85,7 @@ jobs:
 
     steps:
       - name: Repository checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           fetch-depth: 0
 
@@ -103,7 +103,9 @@ jobs:
           path: ${{ steps.ShellCheck.outputs.sarif }}
 ```
 
-> **Warning**: _`fetch-depth: 0` is required to run `differential-shellcheck` successfully. It fetches all git history._
+> **Warning**
+>
+> _`fetch-depth: 0` is required to run `differential-shellcheck` successfully. It fetches all git history._
 
 <details>
   <summary>Console output example</summary>
@@ -112,6 +114,16 @@ jobs:
   </p>
 </details>
 
+<details>
+  <summary>Example of Job Summary</summary>
+  <p align="center">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="docs/images/job-summary-dark.png">
+      <img src="docs/images/job-summary-light.png" width="600" />
+    </picture>
+  </p>
+</details>
+
 <details>
   <summary>Example of output in Changed files tab</summary>
   <p align="center">
@@ -271,7 +283,8 @@ This feature is fully compatible with [exclude-path](#exclude-path) and [include
 * requirements: `optional`
 * example: `"build/**"`
 * example for multiple values:
-  ```
+
+  ```yml
   scan-directory: |
     build/**
     testing

docs/example.sh

@@ -0,0 +1,120 @@
+#!/bin/sh
+# Examples taken from the ShellCheck Gallery of bad code - https://github.com/koalaman/shellcheck#gallery-of-bad-code
+
+# Quoting
+# =======
+
+# echo $1                           # Unquoted variables
+# rm "~/my file.txt"                # Quoted tilde expansion
+# v='--verbose="true"'; cmd $v      # Literal quotes in variables
+# touch $@                          # Unquoted $@
+# echo 'Path is $PATH'              # Variables in single quotes
+# trap "echo Took ${SECONDS}s" 0    # Prematurely expanded trap
+# unset var[i]                      # Array index treated as glob
+
+# Conditionals
+# ============
+
+# [[ n != 0 ]]                      # Constant test expressions
+# [[ -e *.mpg ]]                    # Existence checks of globs
+# [[ $foo==0 ]]                     # Always true due to missing spaces
+# [[ -n "$foo " ]]                  # Always true due to literals
+# [[ $foo =~ "fo+" ]]               # Quoted regex in =~
+# [ foo =~ re ]                     # Unsupported [ ] operators
+# [ $1 -eq "shellcheck" ]           # Numerical comparison of strings
+# [ $n && $m ]                      # && in [ .. ]
+# [[ "$$file" == *.jpg ]]           # Comparisons that can't succeed
+# (( 1 -lt 2 ))                     # Using test operators in ((..))
+# [ x ] & [ y ] | [ z ]             # Accidental backgrounding and piping
+
+# Frequently misused commands
+# ===========================
+
+# grep '*foo*' file                 # Globs in regex contexts
+# find . -exec foo {} && bar {} \;  # Prematurely terminated find -exec
+# sudo echo 'Var=42' > /etc/profile # Redirecting sudo
+# time --format=%s sleep 10         # Passing time(1) flags to time builtin
+# alias archive='mv $1 /backup'     # Defining aliases with arguments
+# tr -cd '[a-zA-Z0-9]'              # [] around ranges in tr
+# exec foo; echo "Done!"            # Misused 'exec'
+# find -name \*.bak -o -name \*~ -delete  # Implicit precedence in find
+# find . -exec foo > bar \;       # Redirections in find
+# f() { whoami; }; sudo f           # External use of internal functions
+
+# Common beginner's mistakes
+# var = 42                          # Spaces around = in assignments
+# $foo=42                           # $ in assignments
+# var$n="Hello"                     # Wrong indirect assignment
+# echo ${var$n}                     # Wrong indirect reference
+# var=(1, 2, 3)                     # Comma separated arrays
+# array=( [index] = value )         # Incorrect index initialization
+# echo $var[14]                     # Missing {} in array references
+# echo "Argument 10 is $10"         # Positional parameter misreference
+# [ false ]                         # 'false' being true
+
+# Style
+# =====
+
+# [[ -z $(find /tmp | grep mpg) ]]  # Use grep -q instead
+# a >> log; b >> log; c >> log      # Use a redirection block instead
+# echo "The time is `date`"         # Use $() instead
+# cd dir; process *; cd ..;         # Use subshells instead
+# echo $[1+2]                       # Use standard $((..)) instead of old $[]
+# echo $(($RANDOM % 6))             # Don't use $ on variables in $((..))
+# echo "$(date)"                    # Useless use of echo
+# cat file | grep foo               # Useless use of cat
+
+# Data and typing errors
+# ======================
+
+# args="$@"                         # Assigning arrays to strings
+# files=(foo bar); echo "$files"    # Referencing arrays as strings
+# declare -A arr=(foo bar)          # Associative arrays without index
+# printf "%s\n" "Arguments: $@."    # Concatenating strings and arrays
+# [[ $# > 2 ]]                      # Comparing numbers as strings
+# var=World; echo "Hello " var      # Unused lowercase variables
+# echo "Hello $name"                # Unassigned lowercase variables
+# cmd | read bar; echo $bar         # Assignments in subshells
+# cat foo | cp bar                  # Piping to commands that don't read
+# printf '%s: %s\n' foo             # Mismatches in printf argument count
+# eval "${array[@]}"                # Lost word boundaries in array eval
+
+# Robustness
+# ==========
+
+# rm -rf "$STEAMROOT/"*            # Catastrophic rm
+# touch ./-l; ls *                 # Globs that could become options
+# find . -exec sh -c 'a && b {}' \; # Find -exec shell injection
+# printf "Hello $name"             # Variables in printf format
+# export MYVAR=$(cmd)              # Masked exit codes
+
+# Portability
+# ===========
+
+# echo {1..$n}                     # Works in ksh, but not bash/dash/sh
+# echo {1..10}                     # Works in ksh and bash, but not dash/sh
+# echo -n 42                       # Works in ksh, bash and dash, undefined in sh
+# expr match str regex             # Unportable alias for `expr str : regex`
+# trap 'exit 42' sigint            # Unportable signal spec
+# cmd &> file                      # Unportable redirection operator
+# read foo < /dev/tcp/host/22      # Unportable intercepted files
+# foo-bar() { ..; }                # Undefined/unsupported function name
+# [ $UID = 0 ]                     # Variable undefined in dash/sh
+# local var=value                  # local is undefined in sh
+# time sleep 1 | sleep 5           # Undefined uses of 'time'
+
+# Miscellaneous
+# =============
+
+# PS1='\e[0;32m\$\e[0m '            # PS1 colors not in \[..\]
+# PATH="$PATH:~/bin"                # Literal tilde in $PATH
+# rm “file”                         # Unicode quotes
+# echo "Hello world"                # Carriage return / DOS line endings
+# echo hello \                      # Trailing spaces after \
+# var=42 echo $var                  # Expansion of inlined environment
+# echo $((n/180*100))               # Unnecessary loss of precision
+# ls *[:digit:].txt                 # Bad character class globs
+# sed 's/foo/bar/' file > file      # Redirecting to input
+# var2=$var2                        # Variable assigned to itself
+# [ x$var = xval ]                  # Antiquated x-comparisons
+# ls() { ls -l "$@"; }              # Infinitely recursive wrapper

src/index.sh

@@ -67,7 +67,7 @@ if ! is_strict_check_on_push_demanded; then
   execute_shellcheck "${only_changed_scripts[@]}" > ../head-shellcheck.err
 
   # Checkout the base branch/commit
-  git checkout --force --quiet -b ci_br_dest "${BASE}"
+  git checkout --force --quiet -b ci_br_dest "${BASE}" || git checkout --force --quiet "${BASE}"
 
   execute_shellcheck "${only_changed_scripts[@]}" > ../base-shellcheck.err
 
@@ -103,7 +103,7 @@ csgrep \
   --set-scan-prop='tool:ShellCheck' \
   --set-scan-prop="tool-version:${shellcheck_version}" \
   --set-scan-prop='tool-url:https://www.shellcheck.net/wiki/' \
-  '../sarif-defects.log' >> output.sarif
+  '../sarif-defects.log' > output.sarif
 
 echo "sarif=output.sarif" >> "${GITHUB_OUTPUT}"