Skip to content

docs/batches: document grouped changeset titles #1797

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
keegancsmith merged 2 commits into from
Jul 1, 2026
+10 −0
Merged

docs/batches: document grouped changeset titles #1797

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9c73f13
docs/batches: document grouped changeset titles
keegancsmith Jun 29, 2026
4323c97
Merge branch 'main' into k/document-transform-group-title
keegancsmith Jul 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions docs/batch-changes/batch-spec-yaml-reference.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -821,6 +821,7 @@ transformChanges:
# Create a separate changeset for all changes in the top-level `go` directory
- directory: go
branch: my-batch-change-go # will replace the `branch` in the `changesetTemplate`
title: Update ${{ steps.path }} # optional: will replace the `title` in the `changesetTemplate`

- directory: internal/codeintel
branch: my-batch-change-codeintel # will replace the `branch` in the `changesetTemplate`
Expand Down Expand Up @@ -862,6 +863,12 @@ The branch that should be used for this additional changeset. This **overwrites
be unique and cannot be used as arguments for multiple `directory` fields.
</Callout>

## `transformChanges.group.title`

(Optional) The title that should be used for this additional changeset. This **overwrites the [`changesetTemplate.title`](#changesettemplate-title)** when creating the additional changeset.

The title supports the same template variables as [`changesetTemplate.title`](#changesettemplate-title). When rendering the group title, `${{ steps.path }}` is set to this group's [`directory`](#transformchangesgroupdirectory).

## `transformChanges.group.repository`

(Optional) The file diffs matching the given directory will only be grouped in a repository with that name, as configured on your Sourcegraph instance.
Expand Down
3 changes: 3 additions & 0 deletions docs/batch-changes/creating-multiple-changesets-in-large-repositories.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,7 @@ transformChanges:
group:
- directory: client
branch: hello-world-client # will replace the `branch` in the `changesetTemplate`
title: Hello World in client # optional: will replace the `title` in the `changesetTemplate`
- directory: docker-images
# Optional: only apply the rule in this repository
repository: github.com/sourcegraph/sourcegraph
Expand Down Expand Up @@ -73,6 +74,8 @@ This batch spec will produce up to 4 changesets in the `github.com/sourcegraph/s

Since code hosts and Git don't allow creating multiple, different changesets on the same branch, it is **required** to specify a unique `branch` for each `directory` that will be used for the additional changesets. That `branch` will overwrite the default branch specified in `changesetTemplate`.

You can optionally specify a `title` for each group. The group title overwrites the default title specified in `changesetTemplate` for the changeset created from that group. It supports the same template variables as `changesetTemplate.title`, and `${{ steps.path }}` is set to the group's `directory`.

If no changes have been made in a `directory` specified in a `group`, no additional changeset will be produced. If the optional `repository` property is specified, only the changes in that repository will be grouped.

<Callout type="info">
Expand Down