README

此库是 Git 命令行工具的 PHP 封装。

它的目的是提供可读的 API，以抽象化在 PHP 进程中执行 Git 命令的某些挑战。具体来说，此库基于 Symfony 框架的 Process 组件，以跨平台的方式执行 Git 命令，并使用 PHP 可用的最佳技术。此库还提供了一个 SSH 封装脚本和 API 方法，让开发者可以通过在 StackOverflow 上的此帖子中使用的技术轻松指定除了默认密钥之外的私钥。最后，预计将在包含工作副本的目录中执行各种命令。尽管这是一个相当简单的问题，但库会透明地处理它，因此开发者无需考虑。

使用方法

use GitWrapper\GitWrapper;

// Initialize the library. If the path to the Git binary is not passed as
// the first argument when instantiating GitWrapper, it is auto-discovered.
require_once 'vendor/autoload.php';
$wrapper = new GitWrapper();

// Optionally specify a private key other than one of the defaults.
$wrapper->setPrivateKey('/path/to/private/key');

// Clone a repo into `/path/to/working/copy`, get a working copy object.
$git = $wrapper->clone('git://github.com/cpliakas/git-wrapper.git', '/path/to/working/copy');

// Create a file in the working copy.
touch('/path/to/working/copy/text.txt');

// Add it, commit it, and push the change.
$git
    ->add('test.txt')
    ->commit('Added the test.txt file as per the examples.')
    ->push();

// Render the output.
print $git->getOutput();

// Stream output of subsequent Git commands in real time to STDOUT and STDERR.
$wrapper->streamOutput();

// Execute an arbitrary git command.
// The following is synonymous with `git config -l`
$wrapper->git('config -l');

所有命令方法都遵循以下范式

$git->command($arg1, $arg2, ..., $options);

将 command 替换为正在执行的 Git 命令，例如 checkout、push 等。 $arg* 参数是作为传递给 Git 命令行工具的参数传递的变量数量的参数。 $options 是一个可选的数组，包含以下格式的命令行选项

$options = array(
    'verbose' => true,   // Passes the "--verbose" flag.
    't' => 'my-branch',  // Passes the "-t my-branch" option.
);

日志记录

使用与 PSR-3 兼容的记录器（如 Monolog）配合日志记录器监听器记录执行的命令。

use GitWrapper\Event\GitLoggerListener;
use Monolog\Logger;
use Monolog\Handler\StreamHandler;

// Log to a file named "git.log"
$log = new Logger('git');
$log->pushHandler(new StreamHandler('git.log', Logger::DEBUG));

// Instantiate the listener, add the logger to it, and register it.
$listener = new GitLoggerListener($log);
$wrapper->addLoggerListener($listener);

$git = $wrapper->clone('git://github.com/cpliakas/git-wrapper.git', '/path/to/working/copy');

// The "git.log" file now has info about the command that was executed above.

安装

可以使用 Composer 安装 Git Wrapper，将库作为依赖项添加到您的 composer.json 文件中。

{
    "require": {
        "cpliakas/git-wrapper": "~1.0"
    }
}

有关安装和用法说明，请参阅 Composer 的文档。

问题

有一些“问题”超出了此库的解决范围，但可能会阻止通过 PHP 运行 Git 的成功实现。以下是执行 PHP 中的 Git 常见挑战的不完整列表。

缺少 HOME 环境变量

有时在 PHP 启动的 Git 进程中未设置 HOME 环境变量。这将导致许多 Git 操作失败。建议将 HOME 环境变量设置为具有以下特征的路径：位于文档根目录之外，并且 Web 服务器具有写入权限。请注意，此环境变量仅针对运行 Git 的进程设置，而不是启动它的 PHP 进程。

$wrapper->setEnvVar('HOME', '/path/to/a/private/writable/dir');

存储持久性很重要，因为 ~/.gitconfig 文件将写入此位置。参见以下“问题”了解为什么这很重要。

缺少身份和配置

许多存储库需要指定姓名和电子邮件地址。此数据通过在命令行上运行 git config [name] [value] 设置，并且配置通常存储在 ~/.gitconfig 文件 中。但是，通过 PHP 执行 Git 时，进程可能具有与通常通过命令行运行 git 的用户不同的家目录。因此，不会向存储库发送任何身份，并且可能会抛出错误。

// Set configuration options globally.
$wrapper->git('config --global user.name "User name"');
$wrapper->git('config --global user.email user@example.com');

// Set configuration options per repository.
$git
    ->config('user.name', 'User name')
    ->config('user.email', 'user@example.com');

向没有更改的存储库提交

在没有任何更改的仓库上运行 git commit 命令不会输出任何内容，但会以状态码 1 退出。因此，库将抛出 GitException，因为它正确地检测到了错误。在运行提交操作之前检查工作副本是否有任何更改是明智的，以防止出现意外的异常。

if ($git->hasChanges()) {
    $git->commit('Committed the changes.');
}

GIT_SSH 包装脚本的权限

在检出时，bin/git-ssh-wrapper.sh 脚本应该是可执行的。如果不是，如果指定了非默认的私钥，git 命令将失败。

$> chmod 0755 ./bin/git-ssh-wrapper.sh

对于开发者

有关本项目支持的 Apache Ant 目标的详细信息，请参阅 PHP Project Starter 的文档。