Merge 974156ccde into 8d94c6ec1a

## what
  - add documentation on using shell command conditionally

  ## how

  ## why

  ## where

  ## usage

.github/workflows/ci.yml

@@ -47,11 +47,14 @@ jobs:
         run: |
           python -m tox
           python -m tox -e coverage_report
-      - uses: codecov/codecov-action@v3
+      - uses: codecov/codecov-action@v5
+        with:
+          fail_ci_if_error: true
+          token: ${{ secrets.CODECOV_TOKEN }}
   fmt:
     name: Format
     runs-on: ubuntu-22.04
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - uses: psf/black@stable
       - uses: isort/isort-action@v1

README.md

@@ -336,6 +336,7 @@ fine-grained control.
 | `stdin` | Allow a command to read from standard input (default: false) |
 | `stdout` | Show a command's output from stdout (default: false) |
 | `stderr` | Show a command's error output from stderr (default: false) |
+| `if` | Run command if a condition is true (default: true) (optional) |
 
 Note that `quiet` controls whether the command (a string) is printed in log
 output, it does not control whether the output from running the command is
@@ -360,6 +361,19 @@ printed (that is controlled by `stdout` / `stderr`). When a command's `stdin` /
     stderr: true
 ```
 
+##### Running shell command conditionally
+
+```yaml
+- shell:
+    - command: apt update && apt upgrade -y
+      if: lsb_release -i | grep -io 'debian'
+      description: Update APT package repository
+
+    - command: dnf update -y
+      if: lsb_release -i | grep -io 'fedora'
+      description: Update DNF package repository
+```
+
 ### Clean
 
 Clean commands specify directories that should be checked for dead symbolic

codecov.yml

@@ -0,0 +1,4 @@
+coverage:
+  status:
+    project: off
+    patch: off

dotbot/plugins/shell.py

@@ -34,6 +34,30 @@ class Shell(Plugin):
                 stdout = item.get("stdout", stdout)
                 stderr = item.get("stderr", stderr)
                 quiet = item.get("quiet", quiet)
+
+                # run shell command if the 'if' key is present
+                # Ex:
+                # - shell:
+                #     - command: echo "This computer is a Mac"
+                #       if: uname -s | grep -i "Darwin"
+                #
+                # Ex: skipping shell command
+                # - shell:
+                #     - command: echo "skip this shell command"
+                #       if: false
+                if "if" in item:
+                    run_if_result = dotbot.util.shell_command(
+                        str(item["if"]),        # this to make sure python doesn't run it. Had a odd behaviour with having the value 'false'. Check Pull Request #321
+                        cwd=self._context.base_directory(),
+                        enable_stdin=False,
+                        enable_stdout=False,
+                        enable_stderr=stderr,
+                    )
+
+                    # if the condition to run the command is false,
+                    # skip running the command
+                    if run_if_result != 0:
+                        continue
             elif isinstance(item, list):
                 cmd = item[0]
                 msg = item[1] if len(item) > 1 else None