src-auth-perms-sync 0.2.2__tar.gz → 0.3.1__tar.gz

src_auth_perms_sync-0.3.1/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @marcleblanc2

{src_auth_perms_sync-0.2.2 → src_auth_perms_sync-0.3.1}/.github/workflows/release.yml

@@ -6,17 +6,17 @@ on:
       - "v*"
   workflow_dispatch:
     inputs:
-      tag:
-        description: "Existing release tag to publish, for example v0.1.0"
+      version:
+        description: "Package version to publish, for example 0.1.0 or v0.1.0"
         required: true
         type: string
 
 permissions:
-  contents: write
+  contents: read
   pull-requests: read
 
 concurrency:
-  group: release-${{ github.event.inputs.tag || github.ref_name }}
+  group: release-${{ github.event_name == 'workflow_dispatch' && inputs.version || github.ref_name }}
   cancel-in-progress: false
 
 defaults:
@@ -24,15 +24,41 @@ defaults:
     shell: bash
 
 jobs:
+  release_ref:
+    name: Resolve release tag
+    runs-on: ubuntu-24.04
+    outputs:
+      tag: ${{ steps.release.outputs.tag }}
+      version: ${{ steps.release.outputs.version }}
+
+    steps:
+      - name: Resolve release tag
+        id: release
+        env:
+          RELEASE_INPUT: ${{ github.event_name == 'workflow_dispatch' && inputs.version || github.ref_name }}
+        run: |
+          release_input="${RELEASE_INPUT}"
+          if [[ ! "${release_input}" =~ ^v?[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "::error title=Invalid release version::Use MAJOR.MINOR.PATCH or vMAJOR.MINOR.PATCH, got '${release_input}'."
+            exit 1
+          fi
+
+          release_version="${release_input#v}"
+          release_tag="v${release_version}"
+          echo "tag=${release_tag}" >> "${GITHUB_OUTPUT}"
+          echo "version=${release_version}" >> "${GITHUB_OUTPUT}"
+
   validate:
     name: Validate
+    needs: release_ref
     uses: ./.github/workflows/validate.yml
     with:
-      ref: ${{ github.event.inputs.tag || github.ref }}
+      ref: ${{ needs.release_ref.outputs.tag }}
       build-package: false
 
   wheelhouse:
     name: ${{ matrix.platform }}-py311 wheelhouse
+    needs: release_ref
     runs-on: ${{ matrix.runs_on }}
     strategy:
       fail-fast: false
@@ -61,7 +87,7 @@ jobs:
         with:
           fetch-depth: 0
           persist-credentials: false
-          ref: ${{ github.event.inputs.tag || github.ref }}
+          ref: ${{ needs.release_ref.outputs.tag }}
 
       - name: Set up Python
         uses: actions/setup-python@v6
@@ -81,8 +107,10 @@ jobs:
 
       - name: Validate release inputs
         id: release
+        env:
+          RELEASE_TAG: ${{ needs.release_ref.outputs.tag }}
         run: |
-          release_tag="${{ github.event.inputs.tag || github.ref_name }}"
+          release_tag="${RELEASE_TAG}"
           if [[ ! "${release_tag}" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
             echo "::error title=Invalid release tag::Use a vMAJOR.MINOR.PATCH tag, got '${release_tag}'."
             exit 1
@@ -100,19 +128,8 @@ jobs:
             exit 1
           fi
 
-          project_version=$(uv run --frozen python - <<'PY'
-          import tomllib
-
-          with open("pyproject.toml", "rb") as pyproject_file:
-              print(tomllib.load(pyproject_file)["project"]["version"])
-          PY
-          )
-          if [[ "v${project_version}" != "${release_tag}" ]]; then
-            echo "::error title=Version mismatch::pyproject.toml version '${project_version}' does not match tag '${release_tag}'."
-            exit 1
-          fi
-
           echo "tag=${release_tag}" >> "${GITHUB_OUTPUT}"
+          echo "version=${release_tag#v}" >> "${GITHUB_OUTPUT}"
 
       - name: Validate runner architecture
         run: |
@@ -131,6 +148,7 @@ jobs:
         id: build
         run: |
           release_tag="${{ steps.release.outputs.tag }}"
+          release_version="${{ steps.release.outputs.version }}"
           release_dir="build/release/${ASSET_BASENAME}"
           wheelhouse_dir="${release_dir}/wheelhouse"
           dist_dir="build/release/dist"
@@ -158,6 +176,22 @@ jobs:
           project_wheel_name="$(basename "${project_wheel_path}")"
           project_source_distribution_path="${project_source_distributions[0]}"
           project_source_distribution_name="$(basename "${project_source_distribution_path}")"
+          case "${project_wheel_name}" in
+            src_auth_perms_sync-"${release_version}"-*.whl)
+              ;;
+            *)
+              echo "::error title=Wheel version mismatch::Expected wheel version ${release_version}, got '${project_wheel_name}'."
+              exit 1
+              ;;
+          esac
+          case "${project_source_distribution_name}" in
+            src_auth_perms_sync-"${release_version}".tar.gz)
+              ;;
+            *)
+              echo "::error title=Source distribution version mismatch::Expected source distribution version ${release_version}, got '${project_source_distribution_name}'."
+              exit 1
+              ;;
+          esac
           project_wheel_checksum_path="${project_wheel_path}.sha256"
           project_source_distribution_checksum_path="${project_source_distribution_path}.sha256"
           if [[ ! -f "${project_wheel_path}" ]]; then
@@ -165,18 +199,27 @@ jobs:
             exit 1
           fi
 
-          uv export \
-            --no-dev \
-            --no-emit-project \
-            --no-hashes \
-            --no-header \
-            --no-annotate \
-            --frozen \
-            --output-file "${requirements_file}"
+          dependency_metadata_dir="$(mktemp -d)"
+          git clone --no-hardlinks . "${dependency_metadata_dir}" >/dev/null
+          (
+            cd "${dependency_metadata_dir}"
+            git checkout --detach "${release_tag}" >/dev/null
+            mkdir -p "$(dirname "${requirements_file}")"
+            uv export \
+              --no-sources \
+              --no-dev \
+              --no-emit-project \
+              --no-hashes \
+              --no-header \
+              --no-annotate \
+              --output-file "${requirements_file}"
+          )
 
+          cp "${dependency_metadata_dir}/${requirements_file}" "${requirements_file}"
           cp "${requirements_file}" "${runtime_requirements_file}"
-          if grep -q '^\./' "${runtime_requirements_file}"; then
+          if grep -Eq '(^-e[[:space:]]|^(\.\.?/)|(^|[[:space:]])file:| @ (\.\.?/|file:))' "${runtime_requirements_file}"; then
             echo "::error title=Unexpected local dependency::Runtime requirements must resolve from PyPI."
+            cat "${runtime_requirements_file}"
             exit 1
           fi
 
@@ -356,19 +399,21 @@ jobs:
 
   github-release:
     name: Publish GitHub release assets
-    needs: [validate, wheelhouse]
+    needs: [release_ref, validate, wheelhouse]
     runs-on: ubuntu-24.04
+    permissions:
+      contents: write
 
     steps:
       - name: Download wheelhouse artifacts
-        uses: actions/download-artifact@v7
+        uses: actions/download-artifact@v8
         with:
           pattern: src-auth-perms-sync-*
           path: release-assets
           merge-multiple: true
 
       - name: Download release notes
-        uses: actions/download-artifact@v7
+        uses: actions/download-artifact@v8
         with:
           name: release-notes
           path: release-notes
@@ -377,8 +422,9 @@ jobs:
         env:
           GH_TOKEN: ${{ github.token }}
           GH_REPO: ${{ github.repository }}
+          RELEASE_TAG: ${{ needs.release_ref.outputs.tag }}
         run: |
-          release_tag="${{ github.event.inputs.tag || github.ref_name }}"
+          release_tag="${RELEASE_TAG}"
           notes_path="$(find release-notes -name release-notes.md -print -quit)"
           mapfile -t release_assets < <(find release-assets -type f | sort)
 
@@ -415,7 +461,7 @@ jobs:
 
     steps:
       - name: Download built distribution
-        uses: actions/download-artifact@v7
+        uses: actions/download-artifact@v8
         with:
           name: pypi-distributions
           path: dist

{src_auth_perms_sync-0.2.2 → src_auth_perms_sync-0.3.1}/.github/workflows/validate.yml

@@ -157,6 +157,7 @@ jobs:
       - name: Check out code
         uses: actions/checkout@v6
         with:
+          fetch-depth: 0
           persist-credentials: false
           ref: ${{ inputs.ref || github.ref }}
 
@@ -208,6 +209,7 @@ jobs:
       - name: Check out code
         uses: actions/checkout@v6
         with:
+          fetch-depth: 0
           persist-credentials: false
           ref: ${{ inputs.ref || github.ref }}
 
@@ -227,8 +229,8 @@ jobs:
       - name: Install uv
         run: python -m pip install "uv==${UV_VERSION}"
 
-      - name: Build wheel
-        run: uv build --wheel --out-dir dist --no-create-gitignore
+      - name: Build distributions
+        run: uv build --wheel --sdist --out-dir dist --no-create-gitignore
 
       - name: Smoke test installed wheel
         run: |

{src_auth_perms_sync-0.2.2 → src_auth_perms_sync-0.3.1}/.gitignore

@@ -11,9 +11,11 @@ __pycache__
 *.gql
 *.py[cod]
 *.py[oc]
+*.swp
 *.yaml
 build/
 dist/
+logs*/
 logs/
 src-auth-perms-sync-runs/
 wheels/

{src_auth_perms_sync-0.2.2 → src_auth_perms_sync-0.3.1}/AGENTS.md

@@ -44,50 +44,27 @@ uv run src-auth-perms-sync --restore backups/<source>/<run>/before.json
 
 ## Release process
 
-- The tagged source commit must already contain the package version it
-  releases. Do not make the customer release workflow edit `pyproject.toml`.
-- Prepare the version bump on a branch. Set `VERSION`, then copy / paste:
-- As part of every release bump, find old release-version literals in
-  `AGENTS.md`, `README.md`, and release snippets, and replace them with the
-  new version where they are meant to stay current.
+- Package versions are derived from Git tags through `hatch-vcs`.
+- `pyproject.toml` must use `dynamic = ["version"]`; do not add a hard-coded
+  `project.version` for releases.
+- The release tag must be `vMAJOR.MINOR.PATCH` and point at a commit reachable
+  from `origin/main`.
+- The release workflow builds from the tag and checks that wheel and source
+  distribution filenames match the tag version before publishing.
+- Do not make the release workflow edit `pyproject.toml` or `uv.lock`.
+- Validate the remote head of `main` before tagging it:
 
 ```bash
 set -euo pipefail
 
-VERSION=0.2.1
-BRANCH="release-v${VERSION}"
+VERSION_INPUT=<next-version>
+VERSION="${VERSION_INPUT#v}"
 
+[[ "${VERSION_INPUT}" =~ ^v?[0-9]+\.[0-9]+\.[0-9]+$ ]]
 git fetch origin --tags --prune
 git switch main
 git pull --ff-only
-git switch -c "${BRANCH}"
-
-uv run python - "${VERSION}" <<'PY'
-from pathlib import Path
-import re
-import sys
-
-version = sys.argv[1]
-path = Path("pyproject.toml")
-text = path.read_text()
-new_text = re.sub(
-    r'(?m)^version = "[^"]+"$',
-    f'version = "{version}"',
-    text,
-    count=1,
-)
-if new_text == text:
-    raise SystemExit("pyproject.toml version was not updated")
-path.write_text(new_text)
-PY
-
-uv lock
-```
-
-- Validate the release candidate before opening / merging the PR:
-
-```bash
-set -euo pipefail
+test "$(git rev-parse HEAD)" = "$(git rev-parse origin/main)"
 
 uv lock --check
 actionlint
@@ -97,57 +74,24 @@ uv run pyright
 uv run python -m unittest discover -s tests
 uv run src-auth-perms-sync --help
 npx --yes markdownlint-cli2@0.22.1
-uv build --wheel --out-dir /tmp/src-auth-perms-sync-release-check --no-create-gitignore
+uv build --wheel --sdist --out-dir /tmp/src-auth-perms-sync-release-check --no-create-gitignore
 rm -rf /tmp/src-auth-perms-sync-release-check
 ```
 
-- Commit, push, open the PR, wait for checks, then merge it. If review is
-  required, stop after `gh pr checks` and ask for review before merging.
+- Tag the remote head of `main` directly:
 
 ```bash
 set -euo pipefail
 
-VERSION=0.2.1
-BRANCH="release-v${VERSION}"
+VERSION_INPUT=<next-version>
+VERSION="${VERSION_INPUT#v}"
 GH_REPO="sourcegraph/src-auth-perms-sync"
 
-git add pyproject.toml uv.lock
-git commit -m "Release v${VERSION}"
-git push -u origin "${BRANCH}"
-
-gh pr create \
-  --repo "${GH_REPO}" \
-  --base main \
-  --head "${BRANCH}" \
-  --title "Release v${VERSION}" \
-  --body "Bump src-auth-perms-sync package metadata to ${VERSION}."
-
-gh pr checks "${BRANCH}" --repo "${GH_REPO}" --watch --fail-fast
-gh pr merge "${BRANCH}" --repo "${GH_REPO}" --squash --delete-branch
-```
-
-- Tag the merged `main` commit. Do not tag a feature branch commit.
-
-```bash
-set -euo pipefail
-
-VERSION=0.2.1
-
+[[ "${VERSION_INPUT}" =~ ^v?[0-9]+\.[0-9]+\.[0-9]+$ ]]
 git fetch origin --tags --prune
-git switch main
-git pull --ff-only
-git tag "v${VERSION}"
+MAIN_COMMIT="$(git rev-parse origin/main)"
+git tag -a "v${VERSION}" "${MAIN_COMMIT}" -m "Release v${VERSION}"
 git push origin "v${VERSION}"
-```
-
-- Watch the customer release workflow and confirm the GitHub release assets
-  are uploaded:
-
-```bash
-set -euo pipefail
-
-VERSION=0.2.1
-GH_REPO="sourcegraph/src-auth-perms-sync"
 
 RUN_ID="$(
   gh run list \
@@ -169,13 +113,13 @@ gh release view "v${VERSION}" --repo "${GH_REPO}"
 ```bash
 set -euo pipefail
 
-VERSION=0.2.1
+VERSION_INPUT=<version-to-fix>
+VERSION="${VERSION_INPUT#v}"
 GH_REPO="sourcegraph/src-auth-perms-sync"
 
+[[ "${VERSION_INPUT}" =~ ^v?[0-9]+\.[0-9]+\.[0-9]+$ ]]
 git fetch origin --tags --prune
-git switch main
-git pull --ff-only
-git tag -f "v${VERSION}" origin/main
+git tag -f -a "v${VERSION}" origin/main -m "Release v${VERSION}"
 git push origin "refs/tags/v${VERSION}" --force
 
 RUN_ID="$(

{src_auth_perms_sync-0.2.2 → src_auth_perms_sync-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: src-auth-perms-sync
-Version: 0.2.2
+Version: 0.3.1
 Summary: Set Sourcegraph permissions from authentication provider data
 Project-URL: Homepage, https://github.com/sourcegraph/src-auth-perms-sync
 Project-URL: Issues, https://github.com/sourcegraph/src-auth-perms-sync/issues
@@ -18,11 +18,11 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.11
 Requires-Dist: json5>=0.14.0
 Requires-Dist: pyyaml>=6.0.3
-Requires-Dist: src-py-lib==0.1.5
+Requires-Dist: src-py-lib[otel]==0.2.1
 Description-Content-Type: text/markdown
 
 # src-auth-perms-sync
-<!-- HUMAN-MAINTAINED — DO NOT EDIT THIS FILE -->
+<!-- HUMAN-MAINTAINED SECTION START — DO NOT EDIT THIS SECTION -->
 
 src-auth-perms-sync automates Sourcegraph's Explicit Permissions GraphQL API,
 setting user-to-repo permissions based on mapping rules, for example:
@@ -41,8 +41,8 @@ Feel free to open issues or PRs, but responses are best effort.
 
 - Release versions are `major.minor.patch`
 - Because this project is still major version 0:
-  - Minor version updates are breaking changes
-  - Patch version updates are not breaking changes
+  - Minor version updates are probably breaking changes
+  - Patch version updates are probably not breaking changes
 
 ## Principles
 
@@ -54,7 +54,7 @@ Feel free to open issues or PRs, but responses are best effort.
   map casts a smaller net of users / repos. This can result in more maps,
   but they will be easier to understand and trust.
 
-- Backup files are saved in `src-auth-perms-sync-runs/<endpoint>/backups/`,
+- Backup files are saved in `src-auth-perms-sync-runs/<src_endpoint>/runs/<run>/`,
   unless the `--no-backup` arg is provided,
   so customers can review the changes made over time,
   and restore to a specific backup file, if needed
@@ -68,7 +68,10 @@ Feel free to open issues or PRs, but responses are best effort.
 
 - One installation of this script can apply separate `maps.yaml` files on
   separate Sourcegraph instances
-  - Be sure to specify the path to the correct `maps.yaml` file for each run
+  - By default, each Sourcegraph instance gets its own generated `maps.yaml`
+    under `src-auth-perms-sync-runs/<src_endpoint>/`
+  - If you pass `--maps-path`, relative paths are resolved from your current
+    working directory
   - Set the `SRC_ENDPOINT` and `SRC_ACCESS_TOKEN` environment variables correctly for each run
 
 ## Prerequisites
@@ -112,102 +115,126 @@ Feel free to open issues or PRs, but responses are best effort.
 
 ## Install
 
-- Requires Python 3.11
+- Requires Python >= 3.11
 - Recommended: Use a Python virtual environment
 
-### Install from a GitHub Release
-
-Use this when the VM can reach GitHub and PyPI during install:
+### Install from PyPI
 
 ```bash
-python3.11 -m venv .venv
-. .venv/bin/activate
-pip install \
-  "https://github.com/sourcegraph/src-auth-perms-sync/releases/download/v0.1.0/src_auth_perms_sync-0.1.0-py3-none-any.whl"
-```
+# Set up virtual environment
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+
+# Install package from PyPI
+python -m pip install src-auth-perms-sync
 
-### Restricted/offline install from a GitHub Release
+# Run the CLI
+src-auth-perms-sync --help
+```
 
-Use this when the VM cannot reach package indexes during install
+### Restricted / offline install from a GitHub Release
 
-Download the .tar.gz file from the GitHub release
+Download the .tar.gz file from [a GitHub release](https://github.com/sourcegraph/src-auth-perms-sync/releases)
 
 ```bash
 tar -xzf src-auth-perms-sync-linux-x64.tar.gz
-python3.11 -m venv .venv
-. .venv/bin/activate
+
 pip install --no-index --find-links ./wheelhouse src-auth-perms-sync
+
+# Run the CLI
+src-auth-perms-sync --help
 ```
 
-After either install method, run the CLI from the activated virtual environment:
+### Import into your own Python script
 
-```bash
-src-auth-perms-sync --help
+```python
+from pathlib import Path
+
+import src_auth_perms_sync as src
+
+config = src.Config(
+    src_endpoint="https://sourcegraph.example.com",
+    src_access_token="sgp_...",
+    maps_path=Path("/absolute/path/to/maps.yaml"),
+    apply=False,  # Dry run (default), set to True to make changes
+)
+
+succeeded = src.Set(config)
+
+# Other command wrappers:
+# succeeded = src.Get(config)
+# succeeded = src.Restore(config)
+# succeeded = src.SyncSamlOrgs(config)
 ```
 
 ## Inputs
 
-- Environment variables
+- Environment variables (CLI), or src.Config args (Python import)
   - `SRC_ENDPOINT`
   - `SRC_ACCESS_TOKEN` from a user with site-admin perms
-  - Supplied via the environment or a `.env` file
   - See [.env.example](./.env.example)
 
-- YAML maps file `src-auth-perms-sync-runs/<endpoint>/maps.yaml`
+- YAML maps file
+  - By default: `src-auth-perms-sync-runs/<src_endpoint>/maps.yaml`
+  - Or pass `--maps-path ./path/to/maps.yaml`
   - A list of mapping rules
   - Each mapping rule takes
-    - A list of filters for users
-    - A list of filters for repos
+    - A map of filters for users
+    - A map of filters for repos
   - See [maps-example.yaml](./maps-example.yaml)
-  - An empty maps.yaml file is created for you on the first --get run
+  - An empty maps.yaml file is created for you on the first `get` run
 
 ## Usage: Permission sync
 
 1. **Get auth providers and code hosts**
 
     ```bash
-    uv run src-auth-perms-sync [--get]
+    src-auth-perms-sync get
     ```
 
     - Queries the Sourcegraph instance for auth providers and code host connections
     - Writes generated reference files `auth-providers.yaml` and `code-hosts.yaml` under
-      `src-auth-perms-sync-runs/<endpoint>/`
+      `src-auth-perms-sync-runs/<src_endpoint>/`
     - Creates an empty `maps.yaml` if it doesn't exist
-    - Runs by default when no command is selected
 
 2. **Configure mapping rules**
 
-    - Edit `maps.yaml`
+    - Edit `src-auth-perms-sync-runs/<src_endpoint>/maps.yaml`
     - Add mapping rules under the `maps:` top level key
     - See [maps-example.yaml](./maps-example.yaml)
 
 3. **Set: Dry run**
 
     ```bash
-    uv run src-auth-perms-sync --set maps.yaml --full
+    src-auth-perms-sync set --full
     ```
 
 4. **Set: Apply**
 
     ```bash
-    uv run src-auth-perms-sync --set maps.yaml --full --apply
+    src-auth-perms-sync set --full --apply
     ```
 
+    - To use a maps file outside the generated endpoint directory, pass an
+      explicit path, for example `--maps-path ./maps.yaml`
+
 5. **Restore: Dry run**
 
     ```bash
-    uv run src-auth-perms-sync \
-      --restore backups/maps.yaml/2026-04-27-08-24-25-set-apply/before.json
+    src-auth-perms-sync restore \
+      --restore-path src-auth-perms-sync-runs/<src_endpoint>/runs/<run>/before.json
     ```
 
     - Roll back the explicit-permissions state on the
       instance to match a previously captured snapshot
+    - Relative `--restore-path` values are resolved from your current working directory
 
 6. **Restore: Apply**
 
     ```bash
-    uv run src-auth-perms-sync \
-      --restore backups/maps.yaml/2026-04-27-08-24-25-set-apply/before.json \
+    src-auth-perms-sync restore \
+      --restore-path src-auth-perms-sync-runs/<src_endpoint>/runs/<run>/before.json \
       --apply
     ```
 
@@ -216,7 +243,7 @@ src-auth-perms-sync --help
 1. **Get user and org metadata**
 
     ```bash
-    uv run src-auth-perms-sync --sync-saml-orgs
+    src-auth-perms-sync sync-saml-orgs
     ```
 
     - Queries the Sourcegraph instance for auth providers, users, users' SAML groups, and orgs
@@ -225,45 +252,45 @@ src-auth-perms-sync --help
 2. **Apply org sync**
 
     ```bash
-    uv run src-auth-perms-sync --sync-saml-orgs --apply
+    src-auth-perms-sync sync-saml-orgs --apply
     ```
 
     - Creates the orgs if they don't exist, and sync the members from the SAML groups to the orgs
-    - `--sync-saml-orgs` can also be added to a `--set` run, to run both at the same time
+    - `--sync-saml-orgs` can also be added to a `set` run, to run both at the same time
 
 ## Options
 
-Run `uv run src-auth-perms-sync --help` for options
+Run `src-auth-perms-sync --help` for options
 
 ## File tree
 
 ```text
-src-auth-perms-sync-runs/endpoint/
+src-auth-perms-sync-runs/<src_endpoint>/
 ├── auth-providers.yaml
 ├── code-hosts.yaml
 ├── maps.yaml
 └── runs
     └── timestamp-command
-        ├── after.json
         ├── before.json
+        ├── after.json
         ├── diff.json
         ├── log.json
         └── maps.yaml
 ```
 
 - The `src-auth-perms-sync-runs` dir is created under your current working directory
-- The `endpoint` dir is created with the hostname from `SRC_ENDPOINT`
+- The `<src_endpoint>` dir is created with the hostname from `SRC_ENDPOINT`
 - If `maps.yaml` doesn't exist already, it'll be created for you
-- `auth-providers.yaml` and `code-hosts.yaml` are created / replaced by the `--get` command,
+- `auth-providers.yaml` and `code-hosts.yaml` are created / replaced by the `get` command,
   for you to copy values from, to use in your `maps.yaml`
-- Only one `maps.yaml` file can be used at a time per Sourcegraph instance, as each `--set --apply`
+- Only one `maps.yaml` file can be used at a time per Sourcegraph instance, as each `set --apply`
   command resets the state on the Sourcegraph instance to the `maps.yaml` file which was used
 - Each run of the script creates a new `timestamp-command` dir under the `runs` dir, with:
+  - A `before.json` file, capturing the before state, which can be used in a restore run
   - A log file
   - A backup copy of the `maps.yaml` file which was used in that run
-  - A `before.json` file, capturing the before state, which can be restored from
 - Runs using `--apply` also create
   - An `after.json` file, capturing the new state
   - A `diff.json` file, a shorter, reviewable file containing the diffs between before and after
 
-<!-- HUMAN-MAINTAINED — DO NOT EDIT THIS FILE -->
+<!-- HUMAN-MAINTAINED SECTION END — DO NOT EDIT ABOVE -->