What Does the Clean Option Do in actions/checkout?

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 at lines 99‑101, where the action evaluates the boolean value using a default of true:

// 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 at lines 19‑21 and declared in 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:

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):

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

Preserve workspace contents:

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

Minimal syntax (relies on default):

- 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 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 lines 19‑21 and the 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. 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 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, and the implementation logic appears in src/input-helper.ts at lines 99‑101.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}