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:
src
).A campaign spec is a YAML file that defines a campaign, including:
Save the following campaign spec as hello-world.campaign.yaml
:
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.yaml
to something likefile:README.md repo:myproject
(to only match repositories whose name containsmyproject
).
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.