# What Does the Clean Option Do in actions/checkout?

> Understand the clean option in actions/checkout. Learn how it removes untracked files and local changes by default, preserving your workspace when set to false.

- Repository: [GitHub Actions/checkout](https://github.com/actions/checkout)
- Tags: how-to-guide
- Published: 2026-07-16

---

**The `clean` option determines whether the action executes `git clean -ffdx && git reset --hard HEAD` before fetching code, with `true` (default) removing all untracked files and local changes, while `false` preserves the existing workspace state.**

The `actions/checkout` repository provides the official GitHub Action for checking out source code, and understanding its `clean` option is essential for controlling workspace hygiene. This input parameter governs whether the action sanitizes the working directory before proceeding with the checkout operation. By default, the action assumes you want a pristine environment, but this behavior can be disabled to preserve generated artifacts between workflow steps.

## How the Clean Option Works Under the Hood

The `clean` input is parsed in [`src/input-helper.ts`](https://github.com/actions/checkout/blob/main/src/input-helper.ts) at lines 99‑101, where the action evaluates the boolean value using a default of `true`:

```typescript
// Clean
result.clean = (core.getInput('clean') || 'true').toUpperCase() === 'TRUE'

```

This implementation defaults to `true` when no value is explicitly provided, as documented in the [`README.md`](https://github.com/actions/checkout/blob/main/README.md) at lines 19‑21 and declared in [`action.yml`](https://github.com/actions/checkout/blob/main/action.yml).

### When Clean Is Enabled (Default Behavior)

When `clean` is set to `true` (the default), the action performs an aggressive reset of the working tree before fetching the requested commit. Specifically, it executes:

```bash
git clean -ffdx && git reset --hard HEAD

```

This command sequence accomplishes two critical tasks:

- `git clean -ffdx` removes all **untracked files** and **ignored files** from the working directory, including directories (`-d`) and using force (`-ff`) to handle nested git repositories.
- `git reset --hard HEAD` discards any local modifications to tracked files, ensuring the repository returns to a pristine state matching the current HEAD.

### When Clean Is Disabled

Setting `clean` to `false` skips the cleaning step entirely. This preserves any untracked files, ignored files, or local modifications left by previous workflow steps. This configuration is particularly useful when you need to maintain build artifacts, cached dependencies, or generated files between steps without re-uploading them as workflow artifacts.

## Practical Configuration Examples

Here are three common patterns for configuring the `clean` option in your workflows:

Default behavior (explicit cleaning):

```yaml
- uses: actions/checkout@v4
  with:
    clean: true  # Explicitly enables git clean (same as default)

```

Preserve workspace contents:

```yaml
- uses: actions/checkout@v4
  with:
    clean: false  # Skip git clean to retain existing files

```

Minimal syntax (relies on default):

```yaml
- uses: actions/checkout@v4
  # clean defaults to true, so git clean runs automatically

```

## Summary

- The `clean` option in `actions/checkout` controls pre-checkout workspace sanitization, defaulting to `true`.
- When enabled, it executes `git clean -ffdx && git reset --hard HEAD` to remove untracked files and local modifications.
- The parsing logic resides in [`src/input-helper.ts`](https://github.com/actions/checkout/blob/main/src/input-helper.ts) lines 99‑101, defaulting to `true` via `(core.getInput('clean') || 'true')`.
- Setting `clean: false` preserves existing workspace contents, useful for maintaining artifacts between steps.
- Documentation is available in [`README.md`](https://github.com/actions/checkout/blob/main/README.md) lines 19‑21 and the [`action.yml`](https://github.com/actions/checkout/blob/main/action.yml) schema definition.

## Frequently Asked Questions

### What happens if I don't specify the clean option in actions/checkout?

If you omit the `clean` input, the action defaults to `true` according to the parsing logic in [`src/input-helper.ts`](https://github.com/actions/checkout/blob/main/src/input-helper.ts). This means the action automatically runs `git clean -ffdx && git reset --hard HEAD` before fetching code, ensuring you start with a completely clean working directory.

### Why would I set clean to false in actions/checkout?

Set `clean` to `false` when you need to preserve files generated by previous workflow steps, such as build outputs, cached dependencies, or temporary data. This avoids the overhead of uploading and downloading artifacts between jobs while keeping the workspace intact for subsequent steps.

### Does clean: true remove files listed in .gitignore?

Yes, when `clean` is `true`, the `git clean -ffdx` command removes both untracked files and ignored files (due to the `-x` flag). The `-ff` flags ensure nested git repositories are also handled, leaving absolutely no residual files in the working directory.

### Where is the clean option documented in the actions/checkout repository?

The `clean` input is documented in [`README.md`](https://github.com/actions/checkout/blob/main/README.md) at lines 19‑21, which states it controls whether to execute `git clean -ffdx && git reset --hard HEAD` before fetching. The input schema is also defined in [`action.yml`](https://github.com/actions/checkout/blob/main/action.yml), and the implementation logic appears in [`src/input-helper.ts`](https://github.com/actions/checkout/blob/main/src/input-helper.ts) at lines 99‑101.