# Re-executing Batch Specs Multiple Times

<p className="subtitle">
	Learn what happens when you need to re-execute batch specs multiple times
	via the Sourcegraph CLI `src` command.
</p>

## Idempotency as goal

One goal behind the [design of Batch Changes](/batch-changes/design) and the `src batch [apply|preview]` commands in the [Sourcegraph CLI](/cli/) is **idempotency**.

Re-applying the same batch spec produces the same batch change and changesets.

In practical terms, a user should be able to run `src batch apply -f my.batch.yaml` multiple times, and if `my.batch.yaml` didn't change, the batch change shouldn't change.

## Exceptions

That can only work if the inputs to the batch spec stay the same, too.

Since a batch spec's [`on.repositoriesMatchingQuery`](/batch-changes/batch-spec-yaml-reference#onrepositoriesmatchingquery) uses Sourcegraph's search functionality to **dynamically** produce a list of repositories in which to execute the [`steps`](/batch-changes/batch-spec-yaml-reference#steps), the list of repositories might change between executions of `src batch apply`.

If that's the case, the `steps` need to be re-executed in any newly found repositories. Changesets in repositories that are not found anymore will be closed and archived in the batch change (see [Updating a batch change](/batch-changes/update-a-batch-change) for more details). In unchanged repositories, [Sourcegraph CLI](/cli/) tries to use cached results to avoid re-executing the `steps`.

## Local caching

Whenever [Sourcegraph CLI](/cli/) re-executes the same batch spec, it checks a **local cache** to see if it already executed the same [`steps`](/batch-changes/batch-spec-yaml-reference#steps) in a given repository.

Whether a cached result can be used is dependent on multiple things:

-   The repository's default branch's revision didn't change (because if new commits have been pushed to the repository, re-executing the `steps` might lead to different results)
-   The `steps` themselves didn't change, including all their inputs, such as [`steps.env`](/batch-changes/batch-spec-yaml-reference#environmentarray), and the `steps.run` field (which can change between executions if it uses [templating](/batch-changes/batch-spec-templating) and is dynamically built from search results)

That also means that [Sourcegraph CLI](/cli/) can use cached results when re-executing a **changed batch spec**, as long as the changes didn't affect the `steps` and the results they produce.

For example, if only the [`changesetTemplate.title`](/batch-changes/batch-spec-yaml-reference#changesettemplatetitle) field has been changed, cached results can be used, since that field doesn't have any influence on the `steps` and their results.