all-repos

克隆所有您的仓库并应用全面更改。

安装

pip install all-repos

CLI

all-repos提供的所有命令行界面均提供以下选项：

• -h / --help：显示使用信息
• -C CONFIG_FILENAME / --config-filename CONFIG_FILENAME：使用非默认配置文件（默认的all-repos.json可以通过环境变量ALL_REPOS_CONFIG_FILENAME更改）。
• --color {auto,always,never}：在输出中使用颜色（默认auto）。

all-repos-complete [options]

为all-repos仓库添加git clone标签补全。

需要jq才能运行。

添加到.bash_profile

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

all-repos-clone [options]

将所有仓库克隆到output_dir。如果再次运行，此命令将更新现有仓库。

选项

• -j JOBS / --jobs JOBS：完成操作将使用的并发作业数。指定0或-1以匹配CPU数量。（默认8）。

示例调用

• all-repos-clone：克隆all-repos.json中指定的仓库
• all-repos-clone -C all-repos2.json：使用非默认配置文件名进行克隆。

all-repos-find-files [options] PATTERN

类似于分布式的git ls-files | grep -P PATTERN。

参数

• 模式：匹配的 Python 正则表达式。

选项

• --repos-with-matches：仅打印匹配的仓库。

示例调用

• all-repos-find-files setup.py：查找所有 setup.py 文件。
• all-repos-find-files --repos setup.py：查找包含 setup.py 的所有仓库。

all-repos-grep [选项] [GIT_GREP_OPTIONS]

类似于分布式的 git grep ...。

选项

• --repos-with-matches：仅打印匹配的仓库。
• GIT_GREP_OPTIONS：将额外参数传递给 git grep。有关可用选项，请参阅 git grep --help。

示例调用

• all-repos-grep pre-commit -- 'requirements*.txt'：查找所有包含 pre-commit 列在需求文件中的仓库。
• all-repos-grep -L six -- setup.py：查找不包含 six 的 setup.py 文件。

all-repos-list-repos [选项]

列出所有克隆的仓库名称。

all-repos-manual [选项]

交互式地对仓库应用手动更改。

注意：all-repos-manual 总是会在 --interactive 自动修复模式下运行。

注意：all-repos-manual 需要 --repos 自动修复选项。

选项

• 自动修复选项：all-repos-manual 是一个自动修复器，支持所有自动修复器选项。
• --branch-name BRANCH_NAME：覆盖自动修复器分支名称（默认 all-repos-manual）。
• --commit-msg COMMIT_MSG（必需）：设置自动修复器的提交消息。

all-repos-sed [选项] 表达式 FILENAMES

类似于分布式的 git ls-files -z -- FILENAMES | xargs -0 sed -i 表达式。

注意：这假设是 GNU sed。如果您在 macOS 上，请使用 Homebrew 安装 gnu-sed。

brew install gnu-sed

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

参数

• 表达式：sed 程序。例如：s/hi/hello/g。
• FILENAMES：文件名通配符（传递给 git ls-files）。

选项

• 自动修复选项：all-repos-sed 是一个自动修复器，支持所有自动修复器选项。
• -r / --regexp-extended：在脚本中使用扩展正则表达式。有关更多详细信息，请参阅 man sed。
• --branch-name BRANCH_NAME：覆盖自动修复器分支名称（默认 all-repos-sed）。
• --commit-msg COMMIT_MSG：覆盖自动修复器提交消息。（默认 git ls-files -z -- FILENAMES | xargs -0 sed -i ... 表达式）。

示例调用

• all-repos-sed 's/foo/bar/g' -- '*'：在所有文件中将 foo 替换为 bar。

配置

配置文件大致如下所示

{
    "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：当运行 all-repos-clone 时，仓库将被克隆到此处。
• source：到 source 的模块导入路径，请参阅以下内置源模块以及编写自己的说明。
• source_settings：特定于源类型的设置，源模块的文档将解释各种可能的值。
• push：到 push 的模块导入路径，请参阅以下内置推送模块以及编写自己的说明。
• push_settings：特定于推送类型的设置，推送模块的文档将解释各种可能的值。
• include（默认 ""）：用于选择仓库的 Python 正则表达式。只有匹配此正则表达式的仓库名称才会被包含。
• exclude（默认 "^$"）：用于排除仓库的 Python 正则表达式。匹配此正则表达式的仓库名称将被排除。
• all_branches（默认 false）：是否克隆所有分支或仅默认上游分支。

源模块

all_repos.source.json_file

克隆文件中列出的所有仓库。该文件必须按如下格式格式化

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

必需 source_settings

• filename：包含仓库的文件，每行一个。

目录位置

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

all_repos.source.github

克隆用户在 GitHub 上可用的所有仓库。

必需 source_settings

• api_key：用户将登录的 API 密钥。
  • 使用 设置选项卡 创建个人访问令牌。
  • 要正常工作所需的最小作用域是 public_repo，但访问私有仓库需要 repo。
• api_key_env：API密钥还可以通过环境变量传递
• username：您将使用的GitHub用户名。

可选的 source_settings

• collaborator（默认 false）：是否包括非所有者但可以作为贡献者贡献的仓库。
• forks（默认 false）：是否包括分支仓库。
• private（默认 false）：是否包括私有仓库。
• archived（默认：false）：是否包括存档仓库。
• base_url（默认：https://api.github.com）是要使用的GitHub API的基础URL（对于GitHub Enterprise支持，请将此设置为 https://{your_domain}/api/v3）。

目录位置

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

all_repos.source.github_forks

克隆来自GitHub上某个仓库的所有分支仓库。

必需 source_settings

• api_key：用户将登录的 API 密钥。
  • 使用 设置选项卡 创建个人访问令牌。
  • 要正常工作所需的最小作用域是 public_repo。
• api_key_env：API密钥还可以通过环境变量传递
• repo：具有分支的仓库

可选的 source_settings

• collaborator（默认 true）：是否包括非所有者但可以作为贡献者贡献的仓库。
• forks（默认 true）：是否包括分支仓库。
• private（默认 false）：是否包括私有仓库。
• archived（默认：false）：是否包括存档仓库。
• base_url（默认：https://api.github.com）是要使用的GitHub API的基础URL（对于GitHub Enterprise支持，请将此设置为 https://{your_domain}/api/v3）。

目录位置

请参阅 all_repos.source.github 的目录结构。

all_repos.source.github_org

从GitHub上的组织克隆所有仓库。

必需 source_settings

• api_key：用户将登录的 API 密钥。
  • 使用 设置选项卡 创建个人访问令牌。
  • 要正常工作所需的最小作用域是 public_repo，但访问私有仓库需要 repo。
• api_key_env：API密钥还可以通过环境变量传递
• org：要克隆的组织

可选的 source_settings

• collaborator（默认 true）：是否包括非所有者但可以作为贡献者贡献的仓库。
• forks（默认 false）：是否包括分支仓库。
• private（默认 false）：是否包括私有仓库。
• archived（默认：false）：是否包括存档仓库。
• base_url（默认：https://api.github.com）是要使用的GitHub API的基础URL（对于GitHub Enterprise支持，请将此设置为 https://{your_domain}/api/v3）。

目录位置

请参阅 all_repos.source.github 的目录结构。

all_repos.source.gitolite

从 gitolite 主机克隆所有可用给用户的仓库。

必需 source_settings

• username：SSH到服务器作为的用户（通常是 git）
• hostname：gitolite服务器的主机名（例如 git.mycompany.com）

gitolite API通过SSH提供。假设当调用 all-repos-clone 时，可以使用在此处配置的用户名和主机名建立SSH连接以查询该API。

可选的 source_settings

• mirror_path（默认 None）：可选的镜像以从中克隆仓库。这是一个Python格式字符串，可以使用变量 repo_name。

  这可以是git理解的内容，例如另一个远程服务器（例如 gitmirror.mycompany.com:{repo_name}）或本地路径（例如 /gitolite/git/{repo_name}.git）。

目录位置

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

all_repos.source.bitbucket

从Bitbucket Cloud上的用户可用的所有仓库克隆。

必需 source_settings

• username：您将使用的Bitbucket用户名。
• app_password：上述用户的登录认证方法
  • 在您的 账户设置 中创建应用程序密码。
  • 我们需要作用域：仓库 -> 读取

all_repos.source.bitbucket_server

从Bitbucket Server上的用户可用的所有仓库克隆。

必需 source_settings

• base_url：Bitbucket服务器URL（例如 bitbucket.domain.com）
• username：您将使用的Bitbucket用户名。
• app_password：上述用户的登录认证方法
  • 在您的 账户设置 中创建应用程序密码。
  • 我们需要作用域：仓库 -> 读取

可选的 source_settings

• project（默认 None）：可选项目以限制对仓库的搜索。

目录位置

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

all_repos.source.gitlab_org

从Gitlab上的组织克隆所有仓库。

必需 source_settings

• api_key：用户将登录的 API 密钥。
  • 使用设置选项卡（例如 https://{gitlab.domain.com}/-/profile/personal_access_tokens）创建个人访问令牌。
  • 我们需要作用域：read_api，read_repository。
• api_key_env：API密钥还可以通过环境变量传递
• org：要克隆的组织

可选的 source_settings

• base_url：（默认 https://gitlab.com/api/v4）Gitlab服务器URL
• archived（默认：false）：是否包括存档仓库。

目录位置

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

编写自己的源

首先创建一个模块。此模块必须具有以下api

Settings 类

此类将接收 source_settings 字典中所有值的键值参数。

实现Settings类的一个简单方法是使用namedtuple

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

在本例中，required_thing设置是一个必需设置，而optional可以省略（并将获得默认值'optional default value'）。

def list_repos(settings: Settings) -> Dict[str, str]: 可调用对象

这个可调用对象将传递你的Settings类的实例。它必须返回一个从{repo_name: repository_url}的映射。其中repo_name是output_dir内的目录名称。

推送模块

all_repos.push.merge_to_master

将分支直接合并到默认分支并推送。它运行的命令大致如下

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

可选的push_settings

• fast_forward（默认：false）：如果为true，则执行快速前进合并（--ff-only）。如果为false，则创建合并提交（--no-ff）。

all_repos.push.github_pull_request

将分支推送到origin，然后为该分支创建github pull request。

必需的push_settings

• api_key：用户将登录的 API 密钥。
  • 使用 设置选项卡 创建个人访问令牌。
  • 要正常工作所需的最小作用域是 public_repo，但访问私有仓库需要 repo。
• api_key_env：API密钥还可以通过环境变量传递
• username：您将使用的GitHub用户名。

可选的push_settings

• fork（默认：false）：（如果适用）将创建一个分支并推送到上游存储库，而不是上游存储库。然后将对上游存储库创建pull request。
• base_url（默认：https://api.github.com）是要使用的GitHub API的基础URL（对于GitHub Enterprise支持，请将此设置为 https://{your_domain}/api/v3）。

all_repos.push.bitbucket_server_pull_request

将分支推送到origin，然后为该分支创建Bitbucket pull request。

必需的push_settings

• base_url：Bitbucket服务器URL（例如 bitbucket.domain.com）
• username：您将使用的Bitbucket用户名。
• app_password：上述用户的登录认证方法
  • 在您的 账户设置 中创建应用程序密码。
  • 我们需要作用域：仓库 -> 读取

all_repos.push.gitlab_pull_request

将分支推送到origin，然后为该分支创建GitLab pull request。

必需的push_settings

• base_url：GitLab服务器URL（例如 https://{gitlab.domain.com}/api/v4）
• api_key：用户将登录的 API 密钥。
  • 使用设置选项卡（例如 https://{gitlab.domain.com}/-/profile/personal_access_tokens）创建个人访问令牌。
  • 我们需要权限：write_repository。
• api_key_env：API密钥还可以通过环境变量传递

all_repos.push.readonly

不执行任何操作。

push_settings

没有可配置的设置readonly。

编写自己的推送模块

首先创建一个模块。此模块必须具有以下api

Settings 类

该类将接收push_settings字典中所有值的键值对参数。

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

这个可调用对象将传递你的Settings类的实例。它应该部署分支。函数将以存储库的根目录作为cwd调用。

编写自动修复程序

自动修复程序将更改应用于所有存储库。

all-repos提供了几个API函数来编写你的自动修复程序

all_repos.autofix_lib.add_fixer_args

def add_fixer_args(parser):

添加自动修复器命令行选项。

选项

• --dry-run：显示将要发生的事情但不推送。
• -i / --interactive：交互式批准/拒绝修复。
• -j JOBS / --jobs JOBS：完成操作将使用的并发作业数。指定0或-1以匹配CPU数量。（默认1）。
• --limit LIMIT：要处理的存储库的最大数量（默认：无限）。
• --author AUTHOR：覆盖提交作者。这直接传递给git commit。例如：--author='Herp Derp <herp.derp@umich.edu>'。
• --repos [REPOS [REPOS ...]]：针对特定存储库运行。这对于与xargs autofixer ... --repos一起使用特别有用。这可以用来指定不由all-repos管理的存储库。

all_repos.autofix_lib.from_cli

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

解析命令行参数并生成autofix_lib原语。返回(repos, config, commit, autofix_settings)。这与fix分开处理，以便修复器可以调整参数。

• find_repos：接受Config作为位置参数的回调。
• msg：提交信息。
• 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_fix：回调，将被每个存储库调用一次。函数被调用时的cwd将是存储库的根目录。

all_repos.autofix_lib.run

def run(*cmd, **kwargs):

包装 subprocess.run，它会打印将要运行的命令。与 subprocess.run 不同，此功能默认为 check=True，除非明确禁用。

示例自动修复器

简单的自动修复器如下

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())

您可以在 all_repos/autofix 中找到一些更复杂的示例

• all_repos.autofix.azure_pipelines_autoupdate：升级已固定 azure pipelines 模板仓库引用。
• all_repos.autofix.pre_commit_autoupdate：运行 pre-commit autoupdate。
• all_repos.autofix.pre_commit_autopep8_migrate：将 autopep8-wrapper 从 pre-commit/pre-commit-hooks 迁移到 mirrors-autopep8。
• all_repos.autofix.pre_commit_cache_dir：更新 pre-commit 1.x 的缓存目录。
• all_repos.autofix.pre_commit_flake8_migrate：将 flake8 从 pre-commit/pre-commit-hooks 迁移到 pycqa/flake8。
• all_repos.autofix.pre_commit_migrate_config：运行 pre-commit migrate-config。
• all_repos.autofix.setup_py_upgrade：运行 setup-py-upgrade 然后运行 setup-cfg-fmt 将 setup.py 迁移到 setup.cfg。