Update a batch change

Learn in detail about how to update your Batch Changes.

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

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

BASH
src batch preview -f YOUR_BATCH_SPEC.yaml

Open the URL to preview the changes that will be made by applying the new batch spec
Click Apply to update the batch change.

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

Apply a new batch spec directly

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 specs

BASH
src batch apply -f YOUR_BATCH_SPEC.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, such as the description, are applied directly when you apply the new batch spec.

Changes affecting the changesets are processed asynchronously to update the 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 the 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 has already created and published a changeset, the existing changeset will be closed on the code host and archived in the batch change
When the changeset has been published and the batch spec is changed in such a way that a commit on the code host will be overwritten, any commits that have been manually added to the changeset on the code host will be deleted

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

Updating a batch change to change its scope

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

YAML
# [...]
 
# Find all repositories that contain a README file, in the GitHub my-company org.
on:
 - repositoriesMatchingQuery: file:README 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:

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

The updated repo: filter 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.

Removing changesets

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

For example, let's say you started with this batch spec:

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

Next, you applied it and published changesets to multiple repositories. You can then modify your repo query only to target a subset of the repositories, for example, by adding the repo parameter:

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

When you apply this new batch spec, all the changesets published in repositories other than my-one-repository will be closed on the code host and archived from the batch change. Archived changesets are still associated with the batch change, but they will appear under the Archived tab on the batch change page instead:

archived-tab

To fully remove the changesets from the batch change, you can detach them from this tab in the UI.

Unpublished and imported changesets will skip archiving and immediately be detached from the batch change instead.

Unarchiving changesets

Archiving is not permanent, and published changesets can be unarchived by reversing the process that archived them. To unarchive a changeset, modify your on property once more to match the repository whose changeset you want to bring back. The easiest way to target an individual repository is by adding an on.repository statement for it:

YAML
# [...]
 
# Find all repositories that contain a README file, in the GitHub my-company org.
on:
 - repositoriesMatchingQuery: file:README repo:github.com/my-company
 # Also include one repository from outside my-company.
 - repository: github.com/another-org/my-one-repository
 
# [...]