all-repos

Clone all your repositories and apply sweeping changes.

Installation

pip install all-repos

CLI

All command line interfaces provided by all-repos provide the following
options:

• -h / --help: show usage information
• -C CONFIG_FILENAME / --config-filename CONFIG_FILENAME: use a non-default
  config file (the default all-repos.json can be changed with the environment
  variable ALL_REPOS_CONFIG_FILENAME).
• --color {auto,always,never}: use color in output (default auto).

all-repos-complete [options]

Add git clone tab completion for all-repos repositories.

Requires jq to function.

Add to .bash_profile:

eval "$(all-repos-complete -C ~/.../all-repos.json --bash)"

all-repos-clone [options]

Clone all the repositories into the output_dir. If run again, this command
will update existing repositories.

Options:

• -j JOBS / --jobs JOBS: how many concurrent jobs will be used to complete
  the operation. Specify 0 or -1 to match the number of cpus. (default 8).

Sample invocations:

• all-repos-clone: clone the repositories specified in all-repos.json
• all-repos-clone -C all-repos2.json: clone using a non-default config
  filename.

all-repos-find-files [options] PATTERN

Similar to a distributed git ls-files | grep -P PATTERN.

Arguments:

• PATTERN: the python regex
  to match.

Options:

• --repos-with-matches: only print repositories with matches.

Sample invocations:

• all-repos-find-files setup.py: find all setup.py files.
• all-repos-find-files --repos setup.py: find all repositories containing
  a setup.py.

all-repos-grep [options] [GIT_GREP_OPTIONS]

Similar to a distributed git grep ....

Options:

• --repos-with-matches: only print repositories with matches.
• GIT_GREP_OPTIONS: additional arguments will be passed on to git grep.
  see git grep --help for available options.

Sample invocations:

• all-repos-grep pre-commit -- 'requirements*.txt': find all repositories
  which have pre-commit listed in a requirements file.
• all-repos-grep -L six -- setup.py: find setup.py files which do not
  contain six.

all-repos-list-repos [options]

List all cloned repository names.

all-repos-manual [options]

Interactively apply a manual change across repos.

note: all-repos-manual will always run in --interactive autofixing mode.

note: all-repos-manual requires the --repos autofixer option.

Options:

• autofix options: all-repos-manual is
  an autofixer and supports all of the autofixer options.
• --branch-name BRANCH_NAME: override the autofixer branch name (default
  all-repos-manual).
• --commit-msg COMMIT_MSG (required): set the autofixer commit message.

all-repos-sed [options] EXPRESSION FILENAMES

Similar to a distributed
git ls-files -z -- FILENAMES | xargs -0 sed -i EXPRESSION.

note: this assumes GNU sed. If you’re on macOS, install gnu-sed with Homebrew:

brew install gnu-sed

# Add to .bashrc / .zshrc
export PATH="$(brew --prefix)/opt/gnu-sed/libexec/gnubin:$PATH"

Arguments:

• EXPRESSION: sed program. For example: s/hi/hello/g.
• FILENAMES: filenames glob (passed to git ls-files).

Options:

• autofix options: all-repos-sed is
  an autofixer and supports all of the autofixer options.
• -r / --regexp-extended: use extended regular expressions in the script.
  See man sed for further details.
• --branch-name BRANCH_NAME override the autofixer branch name (default
  all-repos-sed).
• --commit-msg COMMIT_MSG override the autofixer commit message. (default
  git ls-files -z -- FILENAMES | xargs -0 sed -i ... EXPRESSION).

Sample invocations:

• all-repos-sed 's/foo/bar/g' -- '*': replace foo with bar in all files.

Configuring

A configuration file looks roughly like this:

{
    "output_dir": "output",
    "source": "all_repos.source.github",
    "source_settings":  {
        "api_key": "...",
        "username": "asottile"
    },
    "push": "all_repos.push.github_pull_request",
    "push_settings": {
        "api_key": "...",
        "username": "asottile"
    }
}

• output_dir: where repositories will be cloned to when all-repos-clone is
  run.
• source: the module import path to a source, see below for builtin
  source modules as well as directions for writing your own.
• source_settings: the source-type-specific settings, the source module’s
  documentation will explain the various possible values.
• push: the module import path to a push, see below for builtin push
  modules as well as directions for writing your own.
• push_settings: the push-type-specific settings, the push module’s
  documentation will explain the various possible values.
• include (default ""): python regex for selecting repositories. Only
  repository names which match this regex will be included.
• exclude (default "^$"): python regex for excluding repositories.
  Repository names which match this regex will be excluded.
• all_branches (default false): whether to clone all of the branches or
  just the default upstream branch.

Source modules

all_repos.source.json_file

Clones all repositories listed in a file. The file must be formatted as
follows:

{
    "example/repo1": "https://git.example.com/example/repo1",
    "repo2": "https://git.example.com/repo2"
}

Required source_settings

• filename: file containing repositories one-per-line.

Directory location

output/
+--- repos.json
+--- repos_filtered.json
+--- {repo_key1}/
+--- {repo_key2}/
+--- {repo_key3}/

all_repos.source.github

Clones all repositories available to a user on github.

Required source_settings

• api_key: the api key which the user will log in as.
  • Use the settings tab to create a
    personal access token.
  • The minimum scope required to function is public_repo, though you’ll
    need repo to access private repositories.
• api_key_env: alternatively API key can also be passed via an environment variable
• username: the github username you will log in as.

Optional source_settings

• collaborator (default false): whether to include repositories which are
  not owned but can be contributed to as a collaborator.
• forks (default false): whether to include repositories which are forks.
• private (default false): whether to include private repositories.
• archived (default: false): whether to include archived repositories.
• base_url (default: https://api.github.com) is the base URL to the Github
  API to use (for Github Enterprise support set this to https://{your_domain}/api/v3).

Directory location

output/
+--- repos.json
+--- repos_filtered.json
+--- {username1}/
    +--- {repo1}/
    +--- {repo2}/
+--- {username2}/
    +--- {repo3}/

all_repos.source.github_forks

Clones all repositories forked from a repository on github.

Required source_settings

• api_key: the api key which the user will log in as.
  • Use the settings tab to create a
    personal access token.
  • The minimum scope required to function is public_repo.
• api_key_env: alternatively API key can also be passed via an environment variable
• repo: the repo which has forks

Optional source_settings

• collaborator (default true): whether to include repositories which are
  not owned but can be contributed to as a collaborator.
• forks (default true): whether to include repositories which are forks.
• private (default false): whether to include private repositories.
• archived (default: false): whether to include archived repositories.
• base_url (default: https://api.github.com) is the base URL to the Github
  API to use (for Github Enterprise support set this to https://{your_domain}/api/v3).

Directory location

See the directory structure for
all_repos.source.github.

all_repos.source.github_org

Clones all repositories from an organization on github.

Required source_settings

• api_key: the api key which the user will log in as.
  • Use the settings tab to create a
    personal access token.
  • The minimum scope required to function is public_repo, though you’ll
    need repo to access private repositories.
• api_key_env: alternatively API key can also be passed via an environment variable
• org: the organization to clone from

Optional source_settings

• collaborator (default true): whether to include repositories which are
  not owned but can be contributed to as a collaborator.
• forks (default false): whether to include repositories which are forks.
• private (default false): whether to include private repositories.
• archived (default: false): whether to include archived repositories.
• base_url (default: https://api.github.com) is the base URL to the Github
  API to use (for Github Enterprise support set this to https://{your_domain}/api/v3).

Directory location

See the directory structure for
all_repos.source.github.

all_repos.source.gitolite

Clones all repositories available to a user on a
gitolite host.

Required source_settings

• username: the user to SSH to the server as (usually git)
• hostname: the hostname of your gitolite server (e.g. git.mycompany.com)

The gitolite API is served over SSH. It is assumed that when all-repos-clone
is called, it’s possible to make SSH connections with the username and hostname
configured here in order to query that API.

Optional source_settings

• mirror_path (default None): an optional mirror to clone repositories from.
  This is a Python format string, and can use the variable repo_name.

  This can be anything git understands, such as another remote server (e.g.
  gitmirror.mycompany.com:{repo_name}) or a local path (e.g.
  /gitolite/git/{repo_name}.git).

Directory location

output/
+--- repos.json
+--- repos_filtered.json
+--- {repo_name1}.git/
+--- {repo_name2}.git/
+--- {repo_name3}.git/

all_repos.source.bitbucket

Clones all repositories available to a user on Bitbucket Cloud.

Required source_settings

• username: the Bitbucket username you will log in as.
• app_password: the authentication method for the above user to login with
  • Create an application password within your account settings.
  • We need the scope: Repositories -> Read

all_repos.source.bitbucket_server

Clones all repositories available to a user on Bitbucket Server.

Required source_settings

• base_url: the bitbucket server URL (eg bitbucket.domain.com)
• username: the Bitbucket username you will log in as.
• app_password: the authentication method for the above user to login with
  • Create an application password within your account settings.
  • We need the scope: Repositories -> Read

Optional source_settings

• project (default None): an optional project to restrict the search for repositories.

Directory location

output/
+--- repos.json
+--- repos_filtered.json
+--- {username1}/
    +--- {repo1}/
    +--- {repo2}/
+--- {username2}/
    +--- {repo3}/

all_repos.source.gitlab_org

Clones all repositories from an organization on gitlab.

Required source_settings

• api_key: the api key which the user will log in as.
  • Use the settings tab (eg https://{gitlab.domain.com}/-/profile/personal_access_tokens) to create a
    personal access token.
  • We need the scope: read_api.
• api_key_env: alternatively API key can also be passed via an environment variable
• org: the organization to clone from

Optional source_settings

• base_url: (default https://gitlab.com/api/v4) the gitlab server URL
• archived (default: false): whether to include archived repositories.

Directory location

output/
+--- repos.json
+--- repos_filtered.json
+--- {org}/
    +--- {subpgroup1}/
        +--- {subpgroup2}/
            +--- {repo1}/
        +--- {repo2}/
    +--- {repo3}/
    +--- {repo4}/

Writing your own source

First create a module. This module must have the following api:

A Settings class

This class will receive keyword arguments for all values in the
source_settings dictionary.

An easy way to implement the Settings class is by using a namedtuple:

Settings = collections.namedtuple('Settings', ('required_thing', 'optional'))
Settings.__new__.__defaults__ = ('optional default value',)

In this example, the required_thing setting is a required setting
whereas optional may be omitted (and will get a default value of
'optional default value').

def list_repos(settings: Settings) -> Dict[str, str]: callable

This callable will be passed an instance of your Settings class. It must
return a mapping from {repo_name: repository_url}. The repo_name is the
directory name inside the output_dir.

Push modules

all_repos.push.merge_to_master

Merges the branch directly to the default branch and pushes. The commands it
runs look roughly like this:

git checkout main
git pull
git merge --no-ff $BRANCH
git push origin HEAD

Optional push_settings

• fast_forward (default: false): if true, perform a fast-forward
  merge (--ff-only). If false, create a merge commit (--no-ff).

all_repos.push.github_pull_request

Pushes the branch to origin and then creates a github pull request for the
branch.

Required push_settings

• api_key: the api key which the user will log in as.
  • Use the settings tab to create a
    personal access token.
  • The minimum scope required to function is public_repo, though you’ll
    need repo to access private repositories.
• api_key_env: alternatively API key can also be passed via an environment variable
• username: the github username you will log in as.

Optional push_settings

• base_url (default: https://api.github.com) is the base URL to the Github
  API to use (for Github Enterprise support set this to https://{your_domain}/api/v3).
• draft (default: false) if true will open the pull request as a draft.
• fork (default: false): (if applicable) a fork will be created and pushed
  to instead of the upstream repository. The pull request will then be made
  to the upstream repository.

all_repos.push.bitbucket_server_pull_request

Pushes the branch to origin and then creates a Bitbucket pull request for the branch.

Required push_settings

• base_url: the Bitbucket server URL (eg bitbucket.domain.com)
• username: the Bitbucket username you will log in as.
• app_password: the authentication method for the above user to login with
  • Create an application password within your account settings.
  • We need the scope: Repositories -> Read

all_repos.push.gitlab_pull_request

Pushes the branch to origin and then creates a GitLab pull request for the branch.

Required push_settings

• base_url: the GitLab server URL (eg https://{gitlab.domain.com}/api/v4)
• api_key: the api key which the user will log in as.
  • Use the settings tab (eg https://{gitlab.domain.com}/-/profile/personal_access_tokens) to create a
    personal access token.
  • We need the scope: write_repository.
• api_key_env: alternatively API key can also be passed via an environment variable

all_repos.push.readonly

Does nothing.

push_settings

There are no configurable settings for readonly.

Writing your own push module

First create a module. This module must have the following api:

A Settings class

This class will receive keyword arguments for all values in the push_settings
dictionary.

def push(settings: Settings, branch_name: str) -> None:

This callable will be passed an instance of your Settings class. It should
deploy the branch. The function will be called with the root of the
repository as the cwd.

Writing an autofixer

An autofixer applies a change over all repositories.

all-repos provides several api functions to write your autofixers with:

all_repos.autofix_lib.add_fixer_args

def add_fixer_args(parser):

Adds the autofixer cli options.

Options:

• --dry-run: show what would happen but do not push.
• -i / --interactive: interactively approve / deny fixes.
• -j JOBS / --jobs JOBS: how many concurrent jobs will be used to complete
  the operation. Specify 0 or -1 to match the number of cpus. (default 1).
• --limit LIMIT: maximum number of repos to process (default: unlimited).
• --author AUTHOR: override commit author. This is passed directly to
  git commit. An example: --author='Herp Derp <[email protected]>'.
• --repos [REPOS [REPOS ...]]: run against specific repositories instead.
  This is especially useful with xargs autofixer ... --repos. This can be
  used to specify repositories which are not managed by all-repos.

all_repos.autofix_lib.from_cli

def from_cli(args, *, find_repos, msg, branch_name):

Parse cli arguments and produce autofix_lib primitives. Returns
(repos, config, commit, autofix_settings). This is handled separately from
fix to allow for fixers to adjust arguments.

• find_repos: callback taking Config as a positional argument.
• msg: commit message.
• branch_name: identifier used to construct the branch name.

all_repos.autofix_lib.fix

def fix(
        repos, *,
        apply_fix,
        check_fix=_noop_check_fix,
        config: Config,
        commit: Commit,
        autofix_settings: AutofixSettings,
):

Apply the fix.

• apply_fix: callback which will be called once per repository. The cwd
  when the function is called will be the root of the repository.

all_repos.autofix_lib.run

def run(*cmd, **kwargs):

Wrapper around subprocess.run which prints the command it will run. Unlike
subprocess.run, this defaults check=True unless explicitly disabled.

Example autofixer

The trivial autofixer is as follows:

import argparse

from all_repos import autofix_lib

def find_repos(config):
    return []

def apply_fix():
    pass

def main(argv=None):
    parser = argparse.ArgumentParser()
    autofix_lib.add_fixer_args(parser)
    args = parser.parse_args(argv)

    repos, config, commit, autofix_settings = autofix_lib.from_cli(
        args, find_repos=find_repos, msg='msg', branch_name='branch-name',
    )
    autofix_lib.fix(
        repos, apply_fix=apply_fix, config=config, commit=commit,
        autofix_settings=autofix_settings,
    )

if __name__ == '__main__':
    raise SystemExit(main())

You can find some more involved examples in all_repos/autofix:

• all_repos.autofix.azure_pipelines_autoupdate: upgrade pinned azure
  pipelines template repository references.
• all_repos.autofix.pre_commit_autoupdate: runs pre-commit autoupdate.
• all_repos.autofix.pre_commit_autopep8_migrate: migrates autopep8-wrapper
  from pre-commit/pre-commit-hooks to mirrors-autopep8.
• all_repos.autofix.pre_commit_cache_dir: updates the cache directory
  for travis-ci / appveyor for pre-commit 1.x.
• all_repos.autofix.pre_commit_flake8_migrate: migrates flake8 from
  pre-commit/pre-commit-hooks to pycqa/flake8.
• all_repos.autofix.pre_commit_migrate_config: runs
  pre-commit migrate-config.
• all_repos.autofix.setup_py_upgrade: runs setup-py-upgrade and then
  setup-cfg-fmt to migrate setup.py to setup.cfg.