Merge pull request #19 from buildkite-plugins/Sup-4697-adding-a-clean-checkout-option

[SUP-4697] Adding a clean checkout option

Author: Amna Akram

README.md

@@ -24,9 +24,17 @@ Whether to pass `--no-cone` to `git sparse-checkout` so that the paths are consi
 
 Whether to skip ssh-keyscan step. This will skip adding each ssh public key into the known-hosts file. Only use if ssh keys are already setup.
 
+#### `clean_checkout` ('true' or 'false')
+
+Whether to perform aggressive repository cleanup before checkout. This option handles scenarios where interrupted or cancelled jobs leave the git repository in a corrupted state with uncommitted changes that would prevent checkout. When enabled, it performs `git reset --hard HEAD` and `git sparse-checkout disable` in addition to the normal cleanup. 
+
+**⚠️ Warning:** This option will destroy ALL local changes and remove ALL untracked files. The `git clean -ffxdq` command with the `-x` flag will also remove ignored files (such as credentials, local configuration, or cache files). Only use this option when you're certain no important local data needs to be preserved.
+
+Use this option for pipeline upload jobs that don't need to preserve local changes.
+
 ## Example
 
-Below is an example for using sparse-checkout plugin.
+Below is an example of using sparse-checkout plugin.
 
 ```yaml
 steps:
@@ -38,6 +46,21 @@ steps:
             - .buildkite
 ```
 
+### Handling corrupted repository states
+
+If your jobs are frequently cancelled during the git clone phase, you may encounter failures due to uncommitted changes left in the repository. Use the `clean_checkout` option to handle this:
+
+```yaml
+steps:
+  - label: "Pipeline upload with clean checkout"
+    command: "buildkite-agent pipeline upload"
+    plugins:
+      - sparse-checkout#v1.1.0:
+          paths:
+            - .buildkite
+          clean_checkout: true
+```
+
 ## ⚒ Developing
 
 To run testing, shellchecks and plugin linting use `bk run` with the [Buildkite CLI](https://github.com/buildkite/cli).

hooks/checkout

@@ -19,6 +19,11 @@ else
 fi
 
 SKIP_SSH_KEYSCAN_OPTION="$(plugin_read_config SKIP_SSH_KEYSCAN "false")"
+CLEAN_CHECKOUT_OPTION="$(plugin_read_config CLEAN_CHECKOUT "false")"
+
+if [[ "${CLEAN_CHECKOUT_OPTION}" = "true" ]]; then
+    echo "⚠️  WARNING: clean_checkout is enabled - this will destroy any local changes and reset the repository state"
+fi
 
 if [[ -n "${BUILDKITE_REPO_SSH_HOST:-}" ]] && [[ "${SKIP_SSH_KEYSCAN_OPTION}" = "false" ]] ; then
     echo "Scanning SSH keys for remote git repository"
@@ -41,7 +46,26 @@ if [[ ! -d .git ]]; then
         "${BUILDKITE_REPO}" .
 fi
 
-git clean -ffxdq
+# Enable clean checkout option to deal with corrupted repository states
+if [[ "${CLEAN_CHECKOUT_OPTION}" = "true" ]]; then
+    echo "Clean checkout enabled - resetting repository state"
+    # Remove index lock files
+    find .git -name "*.lock" -delete 2>/dev/null || true
+    # Reset index if corrupted
+      if ! git status >/dev/null 2>&1; then
+          rm -f .git/index 2>/dev/null || true
+      fi
+    # Disable sparse-checkout
+      git sparse-checkout disable 2>/dev/null || true
+    # Clean and reset
+      git clean -ffxdq
+
+      if git rev-parse --verify HEAD >/dev/null 2>&1; then
+          git reset --hard HEAD
+      fi
+  else
+      git clean -ffxdq
+  fi
 
 FETCH_FLAGS=()
 if [[ -n "${BUILDKITE_GIT_FETCH_FLAGS:-}" ]]; then

plugin.yml

@@ -13,6 +13,9 @@ configuration:
     skip_ssh_keyscan:
       type: boolean
       default: false
+    clean_checkout:
+      type: boolean
+      default: false
   required:
     - paths
   additionalProperties: false

tests/checkout.bats

@@ -100,3 +100,70 @@ setup() {
   unstub ssh-keyscan
   unstub git
 }
+
+@test "Clean checkout disabled - uses normal git clean" {
+  export BUILDKITE_PLUGIN_SPARSE_CHECKOUT_CLEAN_CHECKOUT="false"
+
+  stub ssh-keyscan "* : echo 'keyscan'"
+  stub git "clean -ffxdq : echo 'git clean normal'"
+  stub git "fetch --depth 1 origin * : echo 'git fetch'"
+  stub git "sparse-checkout set * * : echo 'git sparse-checkout'"
+  stub git "checkout * : echo 'checkout'"
+
+  run "$PWD"/hooks/checkout
+
+  assert_success
+  assert_output --partial 'git clean normal'
+  refute_output --partial 'Clean checkout enabled'
+
+  unstub ssh-keyscan
+  unstub git
+}
+
+@test "Clean checkout enabled performs aggressive cleanup" {
+  export BUILDKITE_PLUGIN_SPARSE_CHECKOUT_CLEAN_CHECKOUT="true"
+
+  stub ssh-keyscan "* : echo 'keyscan'"
+  stub git "status : echo 'status ok'"
+  stub git "sparse-checkout disable : echo 'git sparse-checkout disable'"
+  stub git "clean -ffxdq : echo 'git clean aggressive'"
+  stub git "rev-parse --verify HEAD : echo 'HEAD'"
+  stub git "reset --hard HEAD : echo 'git reset hard'"
+  stub git "fetch --depth 1 origin * : echo 'git fetch'"
+  stub git "sparse-checkout set * * : echo 'git sparse-checkout'"
+  stub git "checkout * : echo 'checkout'"
+
+  run "$PWD"/hooks/checkout
+
+  assert_success
+  assert_output --partial 'Clean checkout enabled - resetting repository state'
+  assert_output --partial 'git reset hard'
+  assert_output --partial 'git clean aggressive'
+  assert_output --partial 'git sparse-checkout disable'
+
+  unstub ssh-keyscan
+  unstub git
+}
+
+@test "Clean checkout handles repository without HEAD gracefully" {
+  export BUILDKITE_PLUGIN_SPARSE_CHECKOUT_CLEAN_CHECKOUT="true"
+
+  stub ssh-keyscan "* : echo 'keyscan'"
+  stub git "status : echo 'status ok'"
+  stub git "sparse-checkout disable : echo 'sparse-checkout disable'"
+  stub git "clean -ffxdq : echo 'git clean'"
+  stub git "rev-parse --verify HEAD : exit 1"
+  stub git "fetch --depth 1 origin * : echo 'git fetch'"
+  stub git "sparse-checkout set * * : echo 'git sparse-checkout'"
+  stub git "checkout * : echo 'checkout'"
+
+  run "$PWD"/hooks/checkout
+
+  assert_success
+  assert_output --partial 'Clean checkout enabled - resetting repository state'
+  assert_output --partial 'git clean'
+  assert_output --partial 'sparse-checkout disable'
+
+  unstub ssh-keyscan
+  unstub git
+}