README

php-hg 是一个用于与 Mercurial 命令服务器 通信的 VCS 库，而不是在您的代码中到处放置 exec 调用来调用 hg 二进制文件。有关利用命令服务器的提示，请参阅 Mozilla 的提示。

此库支持 hg(1) manpage 中列出的所有命令，包括扩展。

安装

安装此库的最佳方式是通过 composer

composer require gwaz/php-hg

用法

开始使用此库的推荐方法是使用 RepositoryFactory 类。

$factory  = new \PhpHg\RepositoryFactory;
$repo = $factory->make('/path/to/repo');

var_dump($repo->summary()->execute());

在 repo 对象上第一次方法调用应该是您想要运行的命令。它将返回一个 PhpHg\Command 对象，您可以向其中添加参数和参数。

定制工厂

Repository Factory 接受一个或两个可选构造函数参数。第一个是命令加载器。默认加载器使用 Symfony 的 Yaml 解析器从 yaml 文件中加载命令。您可以创建自己的命令加载器，该加载器实现 PhpHg\Contracts\CommandLoader 接口。

$loader = new MyCustomLoader;
$factory  = new RepositoryFactory($loader);

PhpHg\Client 类使用 Symfony 的进程构建器来启动 Mercurial 命令服务器。如果您想使用自定义的 ProcessBuilder 实例，您可以创建一个并将其传递，也可以创建一个指向可执行文件的 HG_BIN 环境变量，它将用于替代。

$builder = (new ProcessBuilder)
    ->setPrefix('/custom/hg/path')
    ->addEnvironmentVariables(['SOME_ENV' => 'SOME_VALUE']);
$factory = new RepositoryFactory(null, $builder);

如果您想添加自定义命令或选项到 repo（例如，如果您启用了自定义扩展），您可以将它们放入与 src 目录中 commands.yaml 文件相同格式的 Yaml 文件中，并将其添加到工厂中。

$factory = new RepositoryFactory;
$factory->addCommandDescriptor('/path/to/custom-commands.yaml');

定制仓库命令

您也可以按仓库基础定制自定义命令。

$repo->addCommands([
  'globalOptions' => [
    'foo' => \PhpHg\Command::OPTION_BOOLEAN
  ],
  'commands' => [
    'bar' => [
      'options' => [/** Some options here **/]
      'arguments' => [/** Some arguments here, if any **/]
    ]
  ]
]);

指定 hg 二进制文件的位置

如果您的 hg 可执行文件不在您的 PATH 中，您可以创建一个自定义构建器，如上所示，或者您也可以指定一个指向可执行文件的 HG_BIN 环境变量，它将用于替代。

运行命令

对任何仓库对象上的第一次方法调用将返回一个该命令的类，然后您可以添加参数和选项，然后在执行命令之前对其进行设置。通过命令对象上的方法调用添加的选项和参数。方法调用的名称与参数或选项的名称匹配。以下是一个示例，用于拉取更改并更新本地仓库。请注意，每个命令必须在设置为所需的状态后，通过 execute() 调用一次，才能实际上在命令服务器上运行它。

$repo->pull()->branch('default')->update()->execute();

选项

在命令行中应包含破折号的选项应以驼峰式形式调用：--foo-bar 应调用为 ->fooBar()。标志类型选项应不带任何参数来设置它们，或使用 FALSE 来取消设置。只能指定一次的选项接受一个字符串作为参数来设置它们，或 NULL 来取消设置。可以多次指定的选项（如 --config）可以有 n 个参数。

$repo->pull()->update(); // --update is a flag argument
$repo->pull()->ssh('/usr/bin/ssh'); // --ssh can only be specified once
$repo->pull()->branch('default', 'new-feature'); // --branch can be specified multiple times

再次调用选项方法将覆盖第一次方法调用。

$repo->pull()->branch('default', 'new-feature')->branch('stable'); // only the 'stable' branch would be pulled

参数

参数应像选项一样通过方法调用。如果一个参数可以重复，它可以像重复选项一样指定。

$repo->clone()->source('http://myrepo.com/repo')->dest('/tmp/repo')->execute()

如果参数是必需的，并且未指定，将抛出异常。

快捷选项

许多命令支持或提供--template选项，并且此选项可以输出的实验性格式之一是JSON或XML。您可以在支持模板的任何命令上调用json()或xml()方法，以获取以该格式返回的数据。

$repo->status()->json()->execute();

扩展

您可以通过遵循与基本src/commands.yaml文件相同的约定的YAML文件轻松添加自定义全局选项或自定义命令。因为使用了Symfony的YAML解析器，所以我们可以利用它将常量包含在YAML中的能力。

YAML文件的基本格式应遵循以下格式

globalOptions:
  option-name: !php/const:PhpHg\Command::OPTION_STRING
commands:
  add:
    options:
      include: !php/const:PhpHg\Command::OPTION_ARRAY
    arguments:
      file: !php/const:PhpHg\Command::ARGUMENT_OPTIONAL_ARRAY

您可以用于选项的常量有

• PhpHg\Command::OPTION_BOOLEAN - 用于标志类型选项
• PhpHg\Command::OPTION_STRING - 用于只能使用一次的选项
• PhpHg\Command::OPTION_ARRAY - 用于可以指定多次的选项

您可以用于参数的常量有

• PhpHg\Command::ARGUMENT_OPTIONAL - 用于可选参数
• PhpHg\Command::ARGUMENT_OPTIONAL_ARRAY - 用于可选但可以指定多次的参数
• PhpHg\Command::ARGUMENT_REQUIRED - 用于必选参数
• PhpHg\Command::ARGUMENT_REQUIRED_ARRAY - 用于必选且可以指定多次的参数

贡献

如果您遇到错误或确定需要某个功能，我们非常愿意了解并接受修复。请为我们打开一个pull请求以便我们审查。如果您尚未签署我们的CLA，您将被要求在我们可以接受您的pull请求之前签署。所有贡献者都必须提供签署的CLA，即使是针对微小错误修复也是如此。

如果您提供pull请求，请确保您的更改包括单元测试，并且整个测试套件都通过。您可以通过命令行使用composer运行测试套件，即composer run-script test。