Have you ever needed to make the same kind of change to many repositories at once? Campaigns make this much easier. To get you started, let’s run a very simple campaign: adding the line
Hello World to all of your repositories’
README.md files. After completing this exercise, you’ll be able to create your own campaigns to make useful changes, fixes, refactors, and more.
You’ll learn how to:
For more detailed information, see “Campaigns” in Sourcegraph documentation.
A campaign lets you make many related code changes, creating many branches and changesets (such as GitHub pull requests) across many repositories. You can track the progress as they are reviewed and merged. See “About campaigns” for more information.
To use campaigns, you need to:
A campaign spec is a YAML file that defines a campaign, including:
Save the following campaign spec as
name: hello-world description: Add Hello World to READMEs # Find all repositories that contain a README.md file. on: - repositoriesMatchingQuery: file:README.md # In each repository, run this command. Each repository's resulting diff is captured. steps: - run: echo Hello World | tee -a $(find -name README.md) container: alpine:3 # Describe the changeset (e.g., GitHub pull request) you want for each repository. changesetTemplate: title: Hello World body: My first campaign! branch: hello-world # Push the commit to this branch. commit: message: Append Hello World to all README.md files published: false
Let’s see the changes that will be made. Don’t worry—no commits, branches, or changesets will be published yet (the repositories on your code host will be untouched).
In your terminal, run this command:
src campaign apply -f hello-world.campaign.yaml -preview
Wait for it to run and compute the changes for each repository.
When it’s done, click the displayed link to see all of the changes that will be made.
Make sure the changes look right.
If you want to run the campaign on fewer repositories, change the roots query in
hello-world.campaign.yamlto something like
file:README.md repo:myproject(to only match repositories whose name contains
Click the Create campaign button.
You created your first campaign! The campaign’s changesets are still unpublished, which means they exist only on Sourcegraph and haven’t been pushed to your code host yet.
Publishing causes commits, branches, and changesets to be created on your code host.
You probably don’t want to publish these toy “Hello World” changesets to actively developed repositories, because that might confuse people (“Why did you add this line to our READMEs?”). On a real campaign, you would click the Publish button next to a changeset to publish it (or the Publish all button to publish all changesets).
You’ve created your first campaign! 🎉🎉
You can customize your campaign spec and experiment with making other types of changes. To update your campaign, edit
hello-world.campaign.yaml and run
src campaign apply -f hello-world.campaign.yaml -preview again. (As before, you’ll see a preview before any changes are applied.)
To learn what else you can do with campaigns, see “Campaigns” in Sourcegraph documentation.