README

此组件帮助查询远程服务，如BitBucket和GitHub以获取仓库列表，并帮助本地克隆以供使用或备份。它提供了一个API和一个命令行界面工具，以下了解更多信息。

要求在composer.json文件中指定

PHP版本 >=5.5
symfony/console版本 >= 2.4
symfony/filesystem版本 >= 2.4
ggioffreda/git版本 >= 0.1.3
guzzlehttp/guzzle版本 >= 6.0
league/event版本 >= 2.0

安装

此组件可以通过composer安装。从命令行运行

$ composer require "ggioffreda/git-guardian" "~0.1"

或者将以下内容添加到您的composer.json文件中的require部分

"require": {
    "ggioffreda/git-guardian": "~0.1"
}

更多信息请查看Packagist上的项目页面Packagist。

API

您可以使用Gioffreda\Component\GitGuardian\GitGuardian类将您的仓库批量克隆到目标位置。以下是一个如何操作的示例

<?php

use Gioffreda\Component\GitGuardian\GitGuardian;

$guardian = new GitGuardian();
$emitter = $guardian->getEmitter();

// initialise your remote adapters

foreach ($remotes as $remote) {
    $guardian->addRemote($remote);
}

$guardian->cloneAll('/var/lib/repositories');

GitGuardian类会发出一系列事件，允许您监控状态

git_guardian.pre_clone_remote和git_guardian.post_clone_remote在获取给定远程的仓库列表之前和之后，以及在克隆它们之前分别发出。这些事件仅针对每个远程适配器发出一次。
git_guardian.pre_clone_repository和git_guardian.post_clone_repository在从远程克隆仓库之前和之后发出。如果仓库已经被克隆，系统将尝试获取所有更改而不是克隆它，因此这些事件可能不会调用以下事件；
git_guardian.create_git在仓库已经在同一目标位置克隆时发出，因此没有克隆；
git_guardian.pre_fetch_repository和git_guardian.post_fetch_repository在本地仓库在克隆时已经可用并且已获取更改（$ git fetch --all）时发出。如果没有要获取的内容，则不会发出这些事件；
git_guardian.config_skip_repository以提高性能并避免无意义的克隆或获取仓库更新，系统使用JSON配置文件来跟踪仓库的更新并保存上次更新仓库的时间戳。如果没有更改仓库，则发出此事件；
git_guardian.pre_config_log_repository在将当前仓库的信息保存到配置文件之前发出。

远程适配器

您可以使用 Gioffreda\Component\GitGuardian\Adapter\BitBucketRemote 类来获取指定用户拥有的仓库列表。如果您提供了OAuth2客户端ID和密钥，您还可以获取私有仓库。以下是一个使用该类的示例：

<?php

use Gioffreda\Component\GitGuardian\Adapter\BitBucketRemote;

$bitBucketCredentials = [
    'client_id' => 'SbALNXBvnN_example',
    'client_secret' => '1JEfYU1n9mm6x4nYhkoC_example'
];

$remote = new BitBucketRemote();
$remote->setOptions($bitBucketCredentials);
$remote->setUser('acme');

您可以通过监听事件 git_remote.repository_discovery 来监听仓库的发现事件，以获取从服务中检索的原始原始定义，例如在控制台中显示消息或获取比从返回的 Gioffreda\Component\GitGuardian\Adapter\BitBucketRepository 对象更多的仓库信息。

<?php

use Gioffreda\Component\GitGuardian\Adapter\BitBucketRemote;

$remote = new BitBucketRemote();
$remote->setOptions([
    'client_id' => 'SbALNXBvnN_example',
    'client_secret' => '1JEfYU1n9mm6x4nYhkoC_example'
]);
$remote->setUser('acme');
$remote->getEmitter()->addListener('git_remote.repository_discovery', function ($event) {
    // do something with it
});

远程适配器可发出以下事件

git_remote.repository_discovery 每次发现并添加到列表中的仓库都会发出；
git_remote.access_token 仅在您提供了OAuth2凭据时才会发出，每次接收到新的访问令牌。如果您打算使用访问令牌在仓库上执行自定义操作，这可能很有用；
git_remote.client_request 每次向远程服务发送API调用时都会发出，并公开被调用的端点。

命令行界面

您可以使用提供的命令 bin/git-guardian 克隆您的仓库或列出您已克隆到本地的已知仓库。命令行界面是使用 Symfony Console Component 构建的，并且可以轻松集成到您的Symfony项目中。

克隆所有仓库

要克隆属于用户的所有仓库，或者如果您指定了多个用户，则可以使用内置命令 git:guardian:clone-all。

例如，要克隆本地 BitBucket 仓库（包括私有仓库），请运行以下内置命令

$ ./bin/git-guardian git:guardian:clone-all \
    --client-id=SbAnN_example --client-secret=1JEfYU1nYhkoC_example \
    ggioffreda

这将克隆给定用户的本地所有仓库。您可以指定目标目录。您可以提供多个用户名或团队名称，以下命令将克隆属于这些用户或团队的仓库。以下是一个示例

$ ./bin/git-guardian git:guardian:clone-all \
    --client-id=SbAnN_example --client-secret=1JEfYU1nYhkoC_example \
    ggioffreda myorganisation mycompany myfriend

上述命令不仅将克隆这些用户或团队的公共仓库，还将克隆您可以访问的所有内容。如果您不提供客户端ID和密钥，则命令将仅克隆公共仓库

$ ./bin/git-guardian git:guardian:clone-all -v \
    ggioffreda myorganisation mycompany myfriend

使用 -v 开关将请求详细输出，以便您可以在命令运行时查看正在发生的情况。

另一个克隆本地 GitHub 仓库（包括私有仓库）的示例是

$ ./bin/git-guardian git:guardian:clone \
    --adapter=GitHub --personal-token=6a67fbb73cd_example \
    ggioffreda

GitHub的身份验证方式略有不同，因此您必须提供您的个人访问令牌和您的用户名，作为您想要克隆的用户/组织的列表中的第一个用户。这将克隆您可以访问的所有私有仓库以及任何其他您在命令行中提供的用户的公共仓库。由于GitHub对用户和组织处理方式不同，您必须按照以下方式提供它们

$ ./bin/git-guardian git:guardian:clone \
    --adapter=GitHub --personal-token=6a67fbb73cd_example \
    ggioffreda orgs/mycompany users/myfriend

您也可以不提供个人访问令牌来克隆仅公共仓库，如下所示

$ ./bin/git-guardian git:guardian:clone \
    --adapter=GitHub users/ggioffreda orgs/mycompany users/myfriend

请注意，现在您的用户名需要被识别为用户而不是组织，否则命令将引发错误。

帮助信息如下

Usage:
  git:guardian:clone-all [options] [--] [<owner>]...

Arguments:
  owner                                The owner or owners of the repositories

Options:
      --adapter=ADAPTER                The adapter to use [default: "BitBucket"]
      --client-id=CLIENT-ID            The client ID (BitBucket only)
      --client-secret=CLIENT-SECRET    The client secret (BitBucket only)
      --personal-token=PERSONAL-TOKEN  The personal access token (GitHub only)
  -d, --destination=DESTINATION        The destination where to clone to [default: ".cloned"]
  -h, --help                           Display this help message
  -q, --quiet                          Do not output any message
  -V, --version                        Display this application version
      --ansi                           Force ANSI output
      --no-ansi                        Disable ANSI output
  -n, --no-interaction                 Do not ask any interactive question
  -v|vv|vvv, --verbose                 Increase the verbosity of messages: 1 for normal output, ...

Help:
 Fetches all the repositories for the given users

列出所有已知仓库

要列出所有已知仓库，请运行以下命令

$ ./bin/git-guardian git:guardian:list-known

您可以指定不同的适配器、仓库克隆的目标位置和不同的格式。可用的格式有

table（默认）此格式对人类分析很有用；
table-borderless 与上述类似，但列之间没有垂直分隔符；
table-compact 与 table 类似，但没有边框
csv 以CSV格式打印列表
tsv 以 TSV 格式打印列表，基本上是使用制表符作为分隔符的 CSV
json 将列表以 JSON 对象的形式打印
json-pretty 将列表以带缩进的 JSON 对象形式打印，以增强可读性

Usage:
  git:guardian:list-known [options]

Options:
      --adapter=ADAPTER          The adapter to use [default: "BitBucket"]
  -d, --destination=DESTINATION  The destination where to clone to [default: ".cloned"]
  -F, --format=FORMAT            The format of the output [default: "table"]
  -h, --help                     Display this help message
  -q, --quiet                    Do not output any message
  -V, --version                  Display this application version
      --ansi                     Force ANSI output
      --no-ansi                  Disable ANSI output
  -n, --no-interaction           Do not ask any interactive question
  -v|vv|vvv, --verbose           Increase the verbosity of messages: 1 for normal output, ...

Help:
 List all known repositories

资源

您可以使用以下命令运行单元测试（需要 PHPUnit）

$ cd path/to/Gioffreda/Component/Git/
$ composer.phar install
$ phpunit

许可证

本软件在以下许可证下分发：GNU GPL v2、GNU GPL v3 和 MIT 许可证。您可以选择最适合您需求的许可证。

ggioffreda / git-guardian

维护者

详细信息

README

安装

API

远程适配器

命令行界面

克隆所有仓库

列出所有已知仓库

资源

许可证