• Introduction
• Installation
• Usage
• Arguments
• Script
• Using All Repositories

If you provide a script Repository Mapper will run it on every repository you specify.

It can help with things like:

• Running structured queries on every repository, E.g.

  • Which repositories still use 'go dep'?
  • How many repositories still depend on X version of this package?
  • Find me all usages of the term 'X' across all repositories
  • Which users contribute to which repositories?

• Running scripts and creating pull requests on every repository. E.g.

  • Auto upgrade X dependency in every repository
  • Add this LICENCE file to every repository

go install github.com/vendasta/repository-mapper@latest

or if you wish to install from source run the following command in the base directory

go install -mod=vendor

Requirements: If you use the --make-pr or -p flag you'll need to install and configure git on your system as the go-git library does not support opening Pull Requests

Let's look at an example invocation to break it down.

repository-mapper \
  --org=vendasta \
  --branch-name=mapper/contributors \
  --script=./test.sh \
  --user-name="[email protected]" \
  --auth-token="auth-token" \
  repo1 repo2 repo3

Let's break it down.

Run repository-mapper -h for usage information

$ repository-mapper -h
Run scripts and queries on repositories across your org

Usage:
  repository-mapper [flags] repos...

Flags:
      --auth-token string         Github auth token (required if not using GitHub CLI)
  -b, --branch-name string        The branch to create. Should be globally unique.
  -d, --description string        Description of the PR
  -h, --help                      help for repository-mapper
  -p, --make-pr                   Create a PR in each repo after running the script
  -o, --org string                The github organization the repos live in.
  -s, --script string             Path to the script to run in each repository
  -t, --title string              Title of the PR
      --user-name string          Github user name (required if not using GitHub CLI)
      --default-branch            (optional) Default branch to checkout when cloning/fetching. (default "master")

Pass as many repositories as you like as positional arguments. Simply provide the short-form name of the repo; e.g. 'my-repo' or 'another-repo'. The organization name will automatically be appended.

To use all recently updated repositories in the organization, see using all repositories.

Repository mapper supports two authentication methods:

1. GitHub CLI (Recommended) Simply authenticate with:

gh auth login

2. Command-line flags If GitHub CLI is not available, provide credentials via flags:

repository-mapper \
  --user-name="your-username" \
  --auth-token="your-token" \
  ...

To generate a personal access token, see this article

The provided script can be any executable. It will be run without any arguments at the root of each repository.

The script must be executable in order for repository-mapper to run it, e.g. chmod +x myscript.sh

All stdout, stderr, and exit code will automatically be collected for you and will be recorded into the json file which is written after each run.

If a script returns a non-zero exit code, repository mapper will not create a commit or pull request in that repository.

You can exit a script with exit code 10 to "skip" the repository and signify there's no work to be done.

Repository directories are automatically cleaned up after processing if:

• A branch was pushed (PR was created), OR
• The repository was skipped (exit code 10)

Failed repositories are kept for debugging purposes. This helps prevent disk space issues when processing many repositories.

Here's one example script:

#!/bin/bash
echo "Hello; let me get those files for you!"
ls

echo "This is what an error looks like" >&2

exit 42

This will result in the result object:

{
  "repo": "my-repo",
  "stdout": "Hello; let me get those files for you!\nfile-1.txt file2.txt",
  "stderr": "This is what an error looks like",
  "exit_code": 42,
  "pull_request": ""
}

If you need to simply get an up-to-date list of all active repositories in your org you can run the get-all-repos script in the scripts directory. It lists to stdout every repo in your org edited in the last year.

The get-all-repos.sh script supports filtering to help you target specific repositories:

Filter by language:

export ORG="vendasta"
./scripts/get-all-repos.sh --language Go

Exclude archived repositories:

./scripts/get-all-repos.sh --language Go --no-archived

Include only archived repositories:

./scripts/get-all-repos.sh --archived

You can easily run a script for each repo that matches your set of filters using

./scripts/get-all-repos.sh --language Python --no-archived | xargs repository-mapper \
  --org=vendasta \
  --branch-name=mapper/update-deps \
  --script=./scripts/upgrade-deps.sh

The script uses GitHub CLI authentication (via gh auth login). Make sure you're authenticated before running it.

See ./scripts/get-all-repos.sh --help for all available options.

Example:

./scripts/get-all-repos.sh --org vendasta

• upgrade-go-deps.sh: Updates provided Go dependencies to their latest versions
• get-all-repos.sh: Lists all repositories in the organization that have been updated in the past year. Requires --org parameter.
• get-contributors.sh: Lists all contributors to the repository
• dep-to-mod.sh: Converts a Go project from using dep to go mod. Uses ORG environment variable (automatically set by repository-mapper).