Add optional "clean" parameter to input of stash/restore action

Sometimes you want to restore stash (for example "~/.cache/" when
it already exists - in which case `gh download` will fail with
error extracting FILE: file exists

While you can delete the directory before restore action is called, it's
a bit more convenient to add optional "clean" input - when set
to "true" and target directory exists, it will delete it and
subsequently re-create the directory.

Author: potiuk

stash/README.md

@@ -72,8 +72,11 @@ Each action (restore and save) has specific inputs tailored to its functionality
 they are specifically modeled after `actions/cache` and `actions/upload-artifact` to provide a drop in replacement.
 Please refer to the action metadata (`action.yml`) for a comprehensive list of inputs, including descriptions and default values.
 
-Additionally the `restore` action has an output `stash-hit` which is set to `true` if the cache was restored successfully,
+The `restore` action has an optional "overwrite" input which defaults to `false` - when set to "true", it
+will delete the existing contents of the target directory before restoring the stash.
+
+Additionally, the `restore` action has an output `stash-hit` which is set to `true` if the cache was restored successfully,
 `false` if no cache was restored and '' if the action failed (an error will be thrown unless `continue-on-error` is set).
 A technical limitation of composite actions like `Stash` is that all outputs are **strings**.
-Therefore an explicit comparison has to be used when using the output:
+Therefore, an explicit comparison has to be used when using the output:
 `if: ${{ steps.restore-stash.outputs.stash-hit == 'true' }}`

stash/restore/action.yml

@@ -28,14 +28,18 @@ inputs:
       To reduce amount of api calls (1000/h/repo limit) the name of the
       current branch will be appended to the key. Key and branchname will be normalized.
     required: true
-
   path:
     description: 'The directory the stash will be restored in.'
     default: ${{ github.workspace }}
 
   token:
     description: 'GITHUB_TOKEN to use to authenticate against the artifacts api.'
     default: ${{ github.token }}
+
+  clean:
+    description: 'Whether the stash_directory should be removed before downloading the stash.'
+    default: 'false'
+
 outputs:
   stash-hit:
     description: >
@@ -139,6 +143,12 @@ runs:
       run: |
         # Catch errors in the download with || to avoid the whole workflow failing
         # when the download times out
+        if [[ "${{ inputs.clean }}" == "true" ]]; then
+            if [[ -d "$STASH_DIR" ]]; then
+                echo "Removing existing stash directory: $STASH_DIR"
+                rm -rf "$STASH_DIR"
+            fi
+        fi
         gh run download "$STASH_RUN_ID" \
                         --name "$STASH_NAME" \
                         --dir "$STASH_DIR" \