Updating a batch change

Updating a batch change works by applying a batch spec to an existing batch change in the same namespace.

Since batch changes are uniquely identified by their name (the name property in the batch spec) and the namespace in which they were created, you can edit any other part of a batch spec and apply it again.

When a new batch spec is applied to an existing batch change the existing batch change is updated and its changesets are updated to match the new desired state.

Requirements

To update a changeset, you need:

admin permissions for the batch change,
write access to the changeset's repository (on the code host), and
a personal access token or a global service account token configured for the code host.

For more information, see Code host interactions in Batch Changes.

Preview and apply a new batch spec

In order to update a batch change after previewing the changes, do the following:

Edit the batch spec with which you created the batch change to include the changes you want to make to the batch change. For example, change the commit message in the changesetTemplate, or add a new changeset id to the importedChangesets, or modify the repositoriesMatchingQuery to return different search results.
Use the Sourcegraph CLI (src) to execute and preview the batch spec.
```
src batch preview -f YOUR_BATCH_SPEC.batch.yaml
```
Open on the URL that's printed to preview the changes that will be made by applying the new batch spec.
Click Apply to update the batch change.

All of the changesets on your code host will be updated to the desired state that was shown in the preview.

Apply a new batch spec directly

In order to update a batch change directly, without preview, do the following:

Edit the batch spec with which you created the batch change to include the changes you want to make to the batch change.
Use the Sourcegraph CLI (src) to execute, upload, and the batch spec.
```
src batch apply -f YOUR_BATCH_SPEC.batch.yaml
```

The new batch spec will be applied directly and the batch change and its changesets will be updated.

How batch change updates are processed

Changes in the batch spec that affect the batch change itself, such as the description, are applied directly when you apply the new batch spec.

Changes that affect the changesets are processed asynchronously to update the changeset to its new desired state. Different fields are processed differently.

Here are some examples:

When the diff or attributes that affect the resulting commit of a changeset directly (such as the changesetTemplate.commit.message or the changesetTemplate.commit.author) and the changeset has been published, the commit on the code host will be overwritten by a new commit that includes the updated diff.
When the changesetTemplate.title or the changesetTemplate.body are changed and the changeset has been published, the changeset on the code host will be updated accordingly.
When the changesetTemplate.branch is changed after the changeset has been published on the code host, the existing changeset will be closed on the code host and new one, with the new branch, will be created.
When the batch spec is changed in such a way that no diff is produced in a repository in which the batch change already created and published a changeset, the existing changeset will be closed on the code host and detached from the batch change.

See the "Batch Changes design" doc for more information on the declarative nature of the Batch Changes system.

Updating a batch change to change its scope

Increasing the number of changesets

You can gradually increase the number of repositories to which a batch change applies by modifying the entries in the on property of the batch spec.

That means you can start with an on property like this in your batch spec:

# [...]

# Find all repositories that contain a README.md file, in the GitHub my-company org.
on:
  - repositoriesMatchingQuery: file:README.md repo:github.com/my-company

# [...]

After you applied that batch spec, you can extend the scope of batch change by changing the on property to result in more repositories:

# [...]

# Find all repositories that contain a README.md file, in the GitHub my-company and my-company-ci org.
on:
  - repositoriesMatchingQuery: file:README.md repo:github.com/my-company|github.com/my-company-ci

# [...]

The updated repo: keyword in the search query will result in more repositories being returned by the search.

If you apply the updated batch spec new changesets will be created for each additional repository.

Decreasing the number of changesets

You can also decrease the number of repositories to which a batch change applies the by modifying the entries in the on property.

If you, for example, started with this batch spec

# [...]

# Find all repositories that contain a README.md file, in the GitHub my-company org.
on:
  - repositoriesMatchingQuery: file:README.md repo:github.com/my-company

# [...]

and applied it and published changesets and then change it to this

# [...]

# Find all repositories that contain a README.md file, in the GitHub my-company org.
on:
  - repositoriesMatchingQuery: file:README.md repo:github.com/my-company/my-one-repository

# [...]

and apply it, then all the changesets that were published in repositories other than my-one-repository will be closed on the code host and detached from the batch change.