Search and replace specific terms
Create a campaign that changes wording in every repository.
Introduction
This tutorial shows you how to create a campaign spec that replaces the words whitelist
and blacklist
with allowlist
and denylist
in every Markdown file across your entire code base.
The campaign spec can be easily changed to search and replace other terms in other file types.
![](https://storage.googleapis.com/sourcegraph-assets/docs/images/campaigns/tutorials/use_allowlist_denylist_wording_teaser.png)
Prerequisites
We recommend using the latest version of Sourcegraph when working with campaigns and that you have a basic understanding of how to create campaign specs and run them. See the following documents for more information:
Create the campaign spec
Save the following campaign spec YAML as allowlist-denylist.campaign.yaml
:
name: use-allowlist-denylist-wording description: This campaign updates our Markdown docs to use the terms "allowlist" and "denylist" instead of "whitelist" and "blacklist". # Search for repositories in which the term "whitelist" or "blacklist" appears # in Markdown files. on: - repositoriesMatchingQuery: whitelist OR blacklist lang:markdown -file:vendor -file:node_modules # In each repository steps: # find all *.md or *.markdown files, that are not in a vendor or node_modules # folder, and replace the terms in them: - run: | find . -type f \( -name '*.md' -or -name '*.markdown' \) -not -path "*/vendor/*" -not -path "*/node_modules/*" |\ xargs sed -i 's/whitelist/allowlist/g; s/blacklist/denylist/g' container: alpine:3 # Describe the changeset (e.g., GitHub pull request) you want for each repository. changesetTemplate: title: Replace whitelist/blacklist with allowlist/denylist body: This replaces the terms whitelist/blacklist in Markdown files with allowlist/denylist branch: campaigns/allowlist-denylist # Push the commit to this branch. commit: message: Replace whitelist/blacklist with allowlist/denylist published: false
Create the campaign
-
In your terminal, run this command:
src campaign preview -f use-allowlist-denylist-wording.campaign.yaml
-
Wait for it to run and compute the changes for each repository.
-
Open the preview URL that the command printed out.
-
Examine the preview. Confirm that the changes are what you intended. If not, edit your campaign spec and then rerun the command above.
-
Click the Apply spec button to create the campaign.
-
Feel free to then publish the changesets (i.e. create pull requests and merge requests) by modifying the
published
attribute in the campaign spec and re-running thesrc campaign preview
command.
ruplacer
to replace terms in multiple case styles
Using With ruplacer we can easily search and replace terms in multiple case styles: white_list
, WhiteList
, WHITE_LIST
etc.
The easiest way to use ruplacer
in our campaign spec would look like this:
steps: # Install and use ruplacer to replace words in case-style variations - run: | cargo install ruplacer \ && find . -type f \( -name '*.md' -or -name '*.markdown' \) -not -path "*/vendor/*" -not -path "*/node_modules/*" >> /tmp/find_result.txt \ && cat /tmp/find_result.txt | while read file; do ruplacer --subvert whitelist allowlist --go ${file} || echo "nothing to replace"; ruplacer --subvert blacklist denylist --go ${file} || echo "nothing to replace"; done # Use the rust image in our container container: rust
But there's a problem with that approach: every new execution of src campaign preview
has to execute the cargo install ruplacer
command again. And if you're tweaking which terms you're replacing, that performance cost can become too much quite fast.
A better option would be to to build a small Docker image in which ruplacer
is already installed.
To do that, save the following in a Dockerfile
:
FROM rust RUN cargo install ruplacer
Then build a Docker image out of it, tagged with ruplacer
, by running the following command in your terminal:
docker build . -t ruplacer
Once that is done, we can use the following steps
in our campaign spec:
steps: - run: | find . -type f \( -name '*.md' -or -name '*.markdown' \) -not -path "*/vendor/*" -not -path "*/node_modules/*" >> /tmp/find_result.txt \ && cat /tmp/find_result.txt | while read file; do ruplacer --subvert whitelist allowlist --go ${file} || echo "nothing to replace"; ruplacer --subvert blacklist denylist --go ${file} || echo "nothing to replace"; done # Use the newly-built ruplacer image container: ruplacer
Save the file and run the src campaign preview
command from above again to use ruplacer
to replace variations of terms.