ghorg

发音为 [gore-guh]；类似于 gorge。你可以使用 ghorg 来大量获取组织仓库。

使用 ghorg 可以快速将一个组织或用户的所有仓库克隆到单个目录中。这在许多情况下都很有用，包括：

使用 ack、silver searcher、grep 等工具搜索组织/用户的代码库
Bash 脚本编写
创建备份
新团队成员入职（克隆所有团队仓库）
执行审计

使用默认配置，ghorg 执行两个操作：

如果仓库不在克隆目录中，将克隆该仓库。

如果仓库已存在于克隆目录中，将对该仓库执行 git pull 和 git clean。

因此，在对同一组织/用户运行 ghorg 第二次时，克隆目录中的所有本地更改默认会被 GitHub 上的内容覆盖。如果你想在此目录下工作，请确保重命名目录或在所有未来的克隆操作中设置 --no-clean 标志，以防止本地更改丢失。

支持的提供商

GitHub（自托管和云端）
- 安装 | 设置 | 示例
GitLab（自托管和云端）
- 安装 | 设置 | 示例
Bitbucket（仅限云端）
- 安装 | 设置 | 示例
Gitea（仅限自托管）
- 安装 | 设置 | 示例

ghorg 使用的术语主要是 GitHub 的术语，即组织/仓库。GitLab 和 BitBucket 使用不同的术语。这里有一个由 GitLab 提供的方便的术语对照表链接。注意，某些功能可能因提供商而异。

安装

有多种安装方法可供选择，请选择适合你的方式：

预编译二进制文件
Homebrew
Golang
Docker
Windows 支持

对于每种安装方法，你可以选择创建 ghorg 配置文件。有关更多详细信息，请参阅配置部分。

mkdir -p $HOME/.config/ghorg
curl https://raw.githubusercontent.com/gabrie30/ghorg/master/sample-conf.yaml > $HOME/.config/ghorg/conf.yaml
vi $HOME/.config/ghorg/conf.yaml # 更新你的配置

预编译二进制文件

查看最新发布以直接下载适用于以下系统的文件：

Mac (Darwin)
Windows
Linux

如果你不确定选择哪个版本，很可能是你操作系统的 x86_64 版本。

Homebrew

brew install gabrie30/utils/ghorg

Golang

# 确保 $HOME/go/bin 在你的 PATH 中 ($ echo $PATH | grep $HOME/go/bin)

# 如果本地使用 go 1.16+ 版本
go install github.com/gabrie30/ghorg@latest

# 较旧的 go 版本可以运行
go get github.com/gabrie30/ghorg

配置

配置的优先级首先给予命令行设置的标志，然后是 $HOME/.config/ghorg/conf.yaml 中设置的内容。这个文件来自 sample-conf.yaml，可以通过以下操作安装：

mkdir -p $HOME/.config/ghorg
curl https://raw.githubusercontent.com/gabrie30/ghorg/master/sample-conf.yaml > $HOME/.config/ghorg/conf.yaml
vi $HOME/.config/ghorg/conf.yaml # 更新你的配置

如果未找到配置文件，ghorg 将使用其默认设置并尝试克隆 GitHub 组织，但始终需要 API 令牌。

你可以有多个配置文件，这在从具有不同令牌和设置的多个 SCM 提供商克隆时很有用。替代配置文件只能作为命令行标志 --config 引用。

如果你有多个不同的组织/用户/配置需要克隆，请参阅 ghorg reclone 命令作为管理它们的方式。

注意：如果设置了 XDG_CONFIG_HOME 环境变量，ghorg 将遵循它。

SCM 提供商设置

注意：如果遇到问题，请阅读下面的故障排除和已知问题部分

GitHub 设置

创建具有所有 repo 权限的个人访问令牌。在 ghorg/conf.yaml 中更新 GHORG_GITHUB_TOKEN，或作为命令行标志，或将其放在文件中并将路径添加到 GHORG_GITHUB_TOKEN。如果你的组织启用了 Saml SSO，你还需要为令牌授予这些权限，参见此文档。
要克隆 GitHub Enterprise（自托管 GitHub 实例）仓库，必须设置 --base-url，例如 ghorg clone <github_org> --base-url=https://internal.github.com
查看 examples/github.md 了解如何运行

GitHub 应用程序认证（高级）

在你的组织中创建一个 GitHub 应用程序。你只需填写必填字段。确保给予仓库权限 -> 内容 -> 只读权限
将 GitHub 应用程序安装到你的组织
从 GitHub 应用程序生成私钥，将密钥位置设置为 GHORG_GITHUB_APP_PEM_PATH
从 GitHub 应用程序找到 GitHub 应用程序 ID，将值设置为 GHORG_GITHUB_APP_ID
从 GitHub 应用程序的 URL 找到 GitHub 安装 ID，将值设置为 GHORG_GITHUB_APP_INSTALLATION_ID。注意：你需要使用实际的 GitHub URL 获取此 ID，转到你的 GitHub 组织设置页面 -> 第三方访问 -> GitHub 应用程序 -> 配置 -> 从 URL 获取 ID

GitLab 设置

创建具有 read_api 权限的个人访问令牌（对于 12.10 之前的自管理 GitLab，使用 api 权限）。可以将此令牌添加到 ghorg/conf.yaml 或作为命令行标志。
在 ghorg/conf.yaml 中更新 GitLab Specific 配置，或通过命令行标志，或将其放在文件中并将路径添加到 GHORG_GITLAB_TOKEN
在 ghorg/conf.yaml 中或通过命令行标志将 GHORG_SCM_TYPE 更新为 gitlab
查看 examples/gitlab.md 了解如何运行

Gitea 设置

创建访问令牌（设置 -> 应用程序 -> 生成令牌）
在 ghorg/conf.yaml 中更新 GHORG_GITEA_TOKEN，或使用 (--token, -t) 标志，或将其放在文件中并将路径添加到 GHORG_GITEA_TOKEN。
在 ghorg/conf.yaml 中或通过命令行标志将 GHORG_SCM_TYPE 更新为 gitea
查看 examples/gitea.md 了解如何运行

Bitbucket 设置

应用程序密码

要配置 Bitbucket，你需要创建一个新的应用程序密码，并更新你的 $HOME/.config/ghorg/conf.yaml，或使用 (--token, -t) 和 (--bitbucket-username) 标志。
在 ghorg/conf.yaml 中或通过命令行标志将SCM 类型更新为 bitbucket
查看 examples/bitbucket.md 了解如何运行

PAT/OAuth 令牌

创建一个 PAT
在 $HOME/.config/ghorg/conf.yaml 中使用 GHORG_BITBUCKET_OAUTH_TOKEN 设置令牌，或使用 --token 标志。确保没有设置 --bitbucket-username。
在 ghorg/conf.yaml 中或通过命令行标志将 SCM 类型更新为 bitbucket
查看 examples/bitbucket.md 了解如何运行

如何使用

查看 examples 目录获取更多特定 SCM 的文档，或使用示例命令，例如 ghorg examples gitlab

$ ghorg clone kubernetes --token=bGVhdmUgYSBjb21tZW50IG9uIGlzc3VlIDY2
# 示例如何使用 --token 和文件路径
$ ghorg clone kubernetes --token=~/.config/ghorg/gitlab-token.txt
$ ghorg clone davecheney --clone-type=user --token=bGVhdmUgYSBjb21tZW50IG9uIGlzc3VlIDY2
$ ghorg clone gitlab-examples --scm=gitlab --preserve-dir --token=bGVhdmUgYSBjb21tZW50IG9uIGlzc3VlIDY2
$ ghorg clone gitlab-examples/wayne-enterprises --scm=gitlab --token=bGVhdmUgYSBjb21tZW50IG9uIGlzc3VlIDY2
$ ghorg clone all-groups --scm=gitlab --base-url=https://gitlab.internal.yourcompany.com --preserve-dir
$ ghorg clone --help
# 查看克隆的资源
$ ghorg ls
$ ghorg ls someorg
$ ghorg ls someorg | xargs -I %s mv %s bar/

更改克隆目录

默认情况下，ghorg 会将组织或用户仓库克隆到类似 $HOME/ghorg/org 的目录中。如果你想将组织克隆到不同的目录，请使用 --path 标志或在 ghorg 配置中设置 GHORG_ABSOLUTE_PATH_TO_CLONE_TO。此值必须是绝对路径。例如，如果你想将 kubernetes 组织克隆到 /tmp/ghorg，你可以运行以下命令。
```
$ ghorg clone kubernetes --path=/tmp/ghorg
```
这将创建...
```
/tmp/ghorg
└── kubernetes
    ├── apimachinery
    ├── gengo
    ├── git-sync
    ├── kubeadm
    ├── kubernetes-template-project
    ├── ...
```
如果你想更改克隆仓库的目录名称，可以在ghorg配置中设置GHORG_OUTPUT_DIR或使用--output-dir标志。例如，要将kubernetes组织中只克隆以sig-开头的仓库到名为kubernetes-sig-only的目录中，可以运行以下命令：

$ ghorg clone kubernetes --match-regex=^sig- --output-dir=kubernetes-sig-only

这将创建以下结构：

$HOME/ghorg
└── kubernetes-sig-only
    ├── sig-release
    ├── sig-security
    └── sig-testing

选择性仓库克隆

使用--match-regex标志只克隆匹配正则表达式的仓库，或使用--exclude-match-regex排除匹配正则表达式的仓库
使用--match-prefix标志只克隆匹配前缀的仓库，或使用--exclude-match-prefix排除匹配前缀的仓库
使用--skip-archived标志在克隆时过滤掉已归档的仓库（不适用于Bitbucket）
使用--skip-forks标志在克隆时过滤掉复刻的仓库
使用GHORG_TOPICS或--topics根据特定的仓库主题进行过滤，只克隆匹配主题的仓库。仅适用于GitHub/GitLab/Gitea
要克隆特定的一组仓库，创建一个文件列出这些仓库的名称（每行一个），然后使用GHORG_TARGET_REPOS或--target-repos-path标志指定该文件的路径
要排除特定仓库不被克隆，可以在$HOME/.config/ghorg目录下创建一个ghorgignore文件。该文件中的每一行应包含仓库的唯一标识符，被视为子字符串。在克隆过程中，这个子字符串会与每个仓库的克隆URL进行比较。如果克隆URL包含ghorgignore文件中列出的子字符串，该仓库将被跳过而不被克隆。为避免无意中排除仓库，请确保ghorgignore文件中的每一行尽可能具体。例如，可以使用https://github.com/gabrie30/ghorg.git或git@github.com:gabrie30/ghorg.git，具体取决于你的克隆方法。这个功能对于永久排除某些仓库特别有用。如果你想使用多个ghorgignore文件或将它们存储在不同位置，可以使用--ghorgignore-path标志指定另一个路径。

# 创建ghorgignore
touch $HOME/.config/ghorg/ghorgignore

# 更新文件
vi $HOME/.config/ghorg/ghorgignore

创建备份

在进行备份时，重要的标志有--backup、--clone-wiki和--include-submodules。--backup标志将使用git clone --mirror克隆仓库。--clone-wiki标志将包含仓库的任何wiki页面。如果你想包含任何子模块，需要使用--include-submodules。最后，如果你想排除任何二进制文件，使用--git-filter=blob:none标志防止它们被克隆。

ghorg clone kubernetes --backup --clone-wiki --include-submodules

这将为该组织创建一个kubernetes_backup目录。里面的每个文件夹将包含源仓库的.git内容。要从.git内容恢复代码，你需要将所有内容移动到.git目录中，然后在该目录内运行git init，然后检出分支，例如：

# 在kubernetes_backup目录内，恢复kubelet源代码
cd kubelet
mkdir .git
mv -f * .git # 将所有内容移动到.git目录
git init
git checkout master

Reclone命令

ghorg reclone命令是一种将所有ghorg clone命令存储在一个配置文件中的方法，使调用长或多个ghorg clone命令更容易。

一旦设置好reclone.yaml配置，你可以调用ghorg reclone来单独克隆每个条目或一次性克隆所有条目，见以下示例：

# 要克隆reclone.yaml中的所有条目，不需要任何参数
ghorg reclone

# 要运行一个或多个条目，可以传递参数
ghorg reclone kubernetes-sig-staging kubernetes-sig

# 查看所有reclone命令
# 注意：此命令会将令牌打印到stdout
ghorg reclone --list

设置

在$HOME/.config/ghorg目录中添加一个reclone.yaml文件。你可以使用以下命令设置一个包含示例的模板：

curl https://raw.githubusercontent.com/gabrie30/ghorg/master/sample-reclone.yaml > $HOME/.config/ghorg/reclone.yaml

更新文件，添加你想运行的命令。

Docker

提供的镜像同时为amd64和arm64架构构建，仅在Github Container Registry ghcr.io上可用。

# 应该打印帮助信息
# 你也可以指定版本作为标签，例如ghcr.io/gabrie30/ghorg:v1.9.9
docker run --rm ghcr.io/gabrie30/ghorg:latest

注意：也有最新主干版本的标签可用，如master或master-<commit SHA 7位字符>，但不推荐使用这些。

ghorg的命令被解析为docker命令。入口点是ghorg二进制文件，因此你只需输入剩余的参数，如下所示：

docker run --rm ghcr.io/gabrie30/ghorg \
    clone kubernetes --token=bGVhdmUgYSBjb21tZW50IG9uIGlzc3VlIDY2

镜像设置了以下环境变量：

GHORG_CONFIG=/config/conf.yaml
GHORG_RECLONE_PATH=/config/reclone.yaml
GHORG_ABSOLUTE_PATH_TO_CLONE_TO=/data

如有必要，可以通过在 docker run 命令中包含 -e 标志来覆盖这些设置，例如 -e GHORG_GITHUB_TOKEN=bGVhdmUgYSBjb21tZW50IG9uIGlzc3VlIDY2。

在主机上持久化数据

为了在主机上存储数据，需要绑定挂载一个卷：

$HOME/.config/ghorg:/config：将您的配置目录挂载到容器内，以访问 config.yaml 和 reclone.yaml。
$HOME/repositories:/data：将您的本地数据目录挂载到容器内，默认情况下，仓库将下载到这里。

docker run --rm \
        -e GHORG_GITHUB_TOKEN=bGVhdmUgYSBjb21tZW50IG9uIGlzc3VlIDY2 \
        -v $HOME/.config/ghorg:/config `# 可选` \
        -v $HOME/repositories:/data \
        ghcr.io/gabrie30/ghorg:latest \
        clone kubernetes --match-regex=^sig

注意：更改 GHORG_ABSOLUTE_PATH_TO_CLONE_TO 将需要将挂载位置从 /data 更改为容器内的新位置。

使用 shell 别名可能会使这更加实用：

alias ghorg="docker run --rm -v $HOME/.config/ghorg:/config -v $HOME/repositories:/data ghcr.io/gabrie30/ghorg:latest"

# 使用别名：创建和清理容器
ghorg clone kubernetes --match-regex=^sig

Windows 支持

当使用 golang 构建或作为预构建二进制文件时，Windows 是受支持的，但是 readme 和其他文档并不针对 Windows 用户。

另外，Windows 用户也可以使用 scoop 安装 ghorg

scoop bucket add main
scoop install ghorg

故障排除

如果您在克隆仓库时遇到问题，请尝试在本地手动克隆其中一个仓库，例如手动运行 git clone https://github.com/your_private_org/your_private_repo.git。如果这不起作用，ghorg 也将无法工作。您的 git 客户端必须首先设置为可以克隆目标仓库。如果您通常使用 ssh 密钥克隆，请在使用 ghorg 时使用 --protocol=ssh 标志。这将获取 ssh 克隆 URL 而不是 https 克隆 URL。
如果您正在克隆一个大型组织，您可能会看到 Error: open /dev/null: too many open files，这意味着您需要增加 ulimits，网上有很多关于这方面的文档。另一个解决方案是减少并发克隆的数量。使用 --concurrency 标志将其设置为低于 25（默认值）。
如果您的 GitHub 组织启用了 SSO，您需要授权您的令牌，请参见此处。
如果您的 GitHub 个人访问令牌只能找到公共仓库，请为您的令牌授予所有仓库权限。
确保您的 $ git --version 大于等于 2.19.0。
检查其他软件，如反恶意软件，可能会干扰 ghorg 创建大量连接的能力，请参见问题 132。您也可以使用 --concurrency=n 降低并发度，默认值为 25。
要自行调试，您可以在调用 ghorg 时设置 GHORG_DEBUG=true 环境变量，例如 GHORG_DEBUG=true ghorg clone kubernetes。注意，当设置此环境变量时，并发度将被设置为 1。
如果您已经走到这一步仍然有问题，请随时提出问题。