Git-PHP

https://github.com/czproject/git-php
Admin
Git-PHP is a PHP library for programmatic Git repository operations, allowing applications to...
Tokens:29,222
Snippets:365
Trust Score:7.6
License:BSD-3-Clause
Update:2 months ago
Show doc for...
Tokens:
Raw
### Windows Escaping Examples

Source: https://github.com/czproject/git-php/blob/master/_autodocs/configuration.md

Examples of how arguments are escaped for Windows environments.

```text
"argument with spaces and special chars"
"quotes are escaped as double-quotes: """
```

--------------------------------

### Command output examples

Source: https://github.com/czproject/git-php/blob/master/_autodocs/api-reference/CommandProcessor.md

Shows the resulting command string for Windows and Unix environments.

```text
set GIT_AUTHOR_NAME=John Doe && set GIT_AUTHOR_EMAIL=john@example.com && git commit -m "test"
```

```text
GIT_AUTHOR_NAME=John Doe GIT_AUTHOR_EMAIL=john@example.com git commit -m 'test'
```

--------------------------------

### Instantiate CommandProcessor with Different Modes

Source: https://github.com/czproject/git-php/blob/master/_autodocs/api-reference/CommandProcessor.md

Examples of initializing the processor with auto-detection or forced platform modes.

```php
// Auto-detect platform
$processor = new CzProject
GitPhp
CommandProcessor;

// Force Windows mode
$processor = new CzProject
GitPhp
CommandProcessor(
    CzProject
GitPhp
CommandProcessor::MODE_WINDOWS
);

// Force Unix mode
$processor = new CzProject
GitPhp
CommandProcessor(
    CzProject
GitPhp
CommandProcessor::MODE_NON_WINDOWS
);
```

--------------------------------

### GitRepository instantiation examples

Source: https://github.com/czproject/git-php/blob/master/_autodocs/configuration.md

Demonstrates various ways to initialize a repository, including path handling and custom runner injection.

```php
// Normal repository directory
$repo = new GitRepository('/var/www/my-project');

// Path ending with .git (stripped automatically)
$repo = new GitRepository('/var/www/my-project/.git');

// Relative path (converted to absolute)
$repo = new GitRepository('./my-project');

// With custom runner
$runner = new MemoryRunner('/test');
$repo = new GitRepository('/test', $runner);
```

--------------------------------

### Unix Escaping Examples

Source: https://github.com/czproject/git-php/blob/master/_autodocs/configuration.md

Examples of how arguments are escaped for Unix environments.

```text
'argument with spaces and special chars'
Special characters automatically escaped
```

--------------------------------

### Configure Git Class Instances

Source: https://github.com/czproject/git-php/blob/master/_autodocs/configuration.md

Examples of initializing the Git class with default settings, custom runners, or specific CliRunner paths.

```php
// Default configuration - uses system 'git' binary
$git = new CzProject\GitPhp\Git;

// Custom runner
$customRunner = new MyCustomRunner;
$git = new CzProject\GitPhp\Git($customRunner);

// Explicit CliRunner with custom git path
$runner = new CzProject\GitPhp\Runners\CliRunner('/usr/bin/git');
$git = new CzProject\GitPhp\Git($runner);
```

--------------------------------

### Configure MemoryRunner for Testing

Source: https://github.com/czproject/git-php/blob/master/_autodocs/configuration.md

Examples of setting up command results, handling errors, and integrating with the Git class for unit testing.

```php
$runner = new MemoryRunner('/path/to/test/repo');

// Setup: command returns multiple lines
$runner->setResult(
    ['branch', '-a'],
    [],
    "* master\n  origin/master\n  feature-x\n  origin/feature-x"
);

// Setup: command with options
$runner->setResult(
    ['commit', ['-m' => 'test message']],
    [],
    "[master abc1234] test message"
);

// Setup: command fails with error
$runner->setResult(
    ['clone', '--end-of-options', 'invalid-url', '/path'],
    [],
    '',
    'fatal: repository not found',
    128
);

// Setup: command output as array of lines
$runner->setResult(
    ['log', '--pretty=format:%s', '-n', '3'],
    [],
    ['First commit', 'Second commit', 'Third commit']
);

// Chaining setResult calls
$runner->setResult(['status'], [], 'nothing to commit')
       ->setResult(['branch'], [], 'master')
       ->setResult(['log', '-1', '--format=%H'], [], 'abc123def456');

// Use with Git class
$git = new CzProject\GitPhp\Git($runner);
$repo = $git->open('/path/to/test/repo');
```

--------------------------------

### Initialize CliRunner

Source: https://github.com/czproject/git-php/blob/master/_autodocs/api-reference/IRunner.md

Constructor definition and usage examples for the CLI-based git runner.

```php
namespace CzProject\GitPhp\Runners;

class CliRunner implements IRunner
{
    public function __construct($gitBinary = 'git')
}
```

```php
// Default: uses 'git' from PATH
$runner = new CliRunner;

// Custom git path
$runner = new CliRunner('/opt/git/bin/git');

// Use with Git class
$git = new CzProject\GitPhp\Git($runner);
```

--------------------------------

### CliRunner Internal Usage

Source: https://github.com/czproject/git-php/blob/master/_autodocs/configuration.md

Example showing how CliRunner automatically instantiates CommandProcessor.

```php
class CliRunner implements IRunner
{
    public function __construct($gitBinary = 'git')
    {
        $this->commandProcessor = new CommandProcessor; // MODE_DETECT
    }
}
```

--------------------------------

### Configure CliRunner Paths

Source: https://github.com/czproject/git-php/blob/master/_autodocs/configuration.md

Examples of setting the git binary path for CliRunner on different operating systems.

```php
// Explicit path on Linux/macOS
$runner = new CliRunner('/usr/local/bin/git');

// Windows with absolute path
$runner = new CliRunner('C:\\Program Files\\Git\\bin\\git.exe');

// Or just the command name if it's in PATH
$runner = new CliRunner('git');
```

--------------------------------

### Install Git-PHP via Composer

Source: https://github.com/czproject/git-php/blob/master/readme.md

Use Composer to add the library to your project dependencies.

```bash
composer require czproject/git-php
```

--------------------------------

### Set Environment Variables

Source: https://github.com/czproject/git-php/blob/master/_autodocs/configuration.md

Example of passing environment variables to git operations.

```php
// In Git::cloneRepository and Git::isRemoteUrlReadable
$env = [
    'GIT_TERMINAL_PROMPT' => 0, // Disable terminal prompts
    // Add custom variables as needed
];

// Internal usage - library sets these for specific operations
```

--------------------------------

### Get Repository Path

Source: https://github.com/czproject/git-php/blob/master/_autodocs/api-reference/GitRepository.md

Retrieve the absolute path of the repository directory.

```php
$path = $repo->getRepositoryPath();
echo $path; // /var/www/my-project
```

--------------------------------

### Testing with MemoryRunner

Source: https://github.com/czproject/git-php/blob/master/_autodocs/api-reference/IRunner.md

Use MemoryRunner to simulate git operations without requiring system I/O or an installed git binary.

```php
// MemoryRunner - no git required, no system I/O
$runner = new MemoryRunner('/test/repo');
$runner->setResult(['status'], [], 'On branch master');
$git = new CzProject\GitPhp\Git($runner);
$repo = $git->open('/test/repo');
```

--------------------------------

### Get Working Directory

Source: https://github.com/czproject/git-php/blob/master/_autodocs/api-reference/IRunner.md

Retrieves the default working directory used by the runner.

```php
function getCwd(): string
```

--------------------------------

### Initialize a New Repository

Source: https://github.com/czproject/git-php/blob/master/readme.md

Create a new repository, optionally passing parameters like --bare.

```php
$repo = $git->init('/path/to/repo-directory');
```

```php
$repo = $git->init('/path/to/repo-directory', [
	'--bare', // creates bare repo
]);
```

--------------------------------

### getCommit($commitId)

Source: https://github.com/czproject/git-php/blob/master/_autodocs/api-reference/GitRepository.md

Gets the Commit object for a specific commit ID.

```APIDOC
## getCommit($commitId)

### Description
Gets the Commit object for a specific commit ID.

### Signature
`public function getCommit($commitId): Commit`

### Parameters
- **commitId** (string|CommitId) - Required - Commit SHA-1 hash or CommitId object.

### Returns
- **Commit** - Commit object with all metadata.

### Throws
- **GitException** - If commit not found or git log fails.
```

--------------------------------

### getLastCommit()

Source: https://github.com/czproject/git-php/blob/master/_autodocs/api-reference/GitRepository.md

Gets the Commit object for the last commit on the current branch.

```APIDOC
## getLastCommit()

### Description
Gets the Commit object for the last commit on the current branch.

### Signature
`public function getLastCommit(): Commit`

### Returns
- **Commit** - Last commit with all metadata.

### Throws
- **GitException** - If git log commands fail.
```

--------------------------------

### Initialize GitRepository

Source: https://github.com/czproject/git-php/blob/master/_autodocs/api-reference/GitRepository.md

Instantiate a new GitRepository object by providing the absolute path to the repository.

```php
$repo = new CzProject\GitPhp\GitRepository('/path/to/repo');
```

--------------------------------

### init($directory, ?array $params = NULL)

Source: https://github.com/czproject/git-php/blob/master/_autodocs/api-reference/Git.md

Initializes a new Git repository in a directory.

```APIDOC
## init($directory, ?array $params = NULL)

### Description
Initializes a new Git repository in a directory.

### Parameters
- **directory** (string) - Required - Path where the repository will be created.
- **params** (array|NULL) - Optional - Additional git init options (e.g., ['--bare']).

### Returns
- **GitRepository** - Newly initialized repository object.

### Throws
- **GitException** - Repository already exists in the directory.
- **GitException** - Unable to create the directory.
- **GitException** - Git init command fails.
```

--------------------------------

### Instantiating and Using Helpers Class

Source: https://github.com/czproject/git-php/blob/master/_autodocs/api-reference/Helpers.md

Demonstrates that the class cannot be instantiated and shows the correct way to call static methods.

```php
try {
    $helpers = new CzProject\GitPhp\Helpers;
} catch (CzProject\GitPhp\StaticClassException $e) {
    echo "Cannot instantiate static class";
}

// Correct usage - static methods only
$result = CzProject\GitPhp\Helpers::isAbsolute('/path');
```

--------------------------------

### IRunner::getCwd()

Source: https://github.com/czproject/git-php/blob/master/_autodocs/api-reference/IRunner.md

Gets the current working directory that the runner uses by default.

```APIDOC
## getCwd()

### Description
Gets the current working directory that the runner uses by default.

### Returns
- **string** - Absolute path to the working directory.
```

--------------------------------

### Initialize a Git Repository

Source: https://github.com/czproject/git-php/blob/master/_autodocs/INDEX.md

Creates a new Git repository at the specified path.

```php
$git = new CzProject\GitPhp\Git;
$repo = $git->init('/path/to/repo');
```

--------------------------------

### Initialize New Repository

Source: https://github.com/czproject/git-php/blob/master/_autodocs/api-reference/Git.md

Create a new Git repository in a specified directory, optionally passing initialization parameters.

```php
// Basic initialization
$repo = $git->init('/path/to/new-repo');

// Bare repository
$repo = $git->init('/path/to/bare-repo', ['--bare']);
```

--------------------------------

### Initialize GitRepository

Source: https://github.com/czproject/git-php/blob/master/_autodocs/configuration.md

Defines the constructor signature for creating a new repository instance.

```php
public function __construct($repository, ?IRunner $runner = NULL)
```

--------------------------------

### getLastCommitId()

Source: https://github.com/czproject/git-php/blob/master/_autodocs/api-reference/GitRepository.md

Gets the commit ID (SHA-1 hash) of the last commit on the current branch.

```APIDOC
## getLastCommitId()

### Description
Gets the commit ID (SHA-1 hash) of the last commit on the current branch.

### Signature
`public function getLastCommitId(): CommitId`

### Returns
- **CommitId** - Last commit ID object.

### Throws
- **GitException** - If git log command fails.
```

--------------------------------

### Perform Basic Repository Operations

Source: https://github.com/czproject/git-php/blob/master/readme.md

Initialize a Git object, open a repository, and perform file operations followed by a commit.

```php
$git = new CzProject\GitPhp\Git;
// create repo object
$repo = $git->open('/path/to/repo');

// create a new file in repo
$filename = $repo->getRepositoryPath() . '/readme.txt';
file_put_contents($filename, "Lorem ipsum
	dolor
	sit amet
");

// commit
$repo->addFile($filename);
$repo->commit('init commit');
```

--------------------------------

### Process Complex Arguments

Source: https://github.com/czproject/git-php/blob/master/_autodocs/api-reference/CommandProcessor.md

Example of processing a complex array of arguments including flags and values.

```php
$args = [
    'remote', 'add',
    ['--track' => true],
    '--end-of-options',
    'origin',
    'git@github.com:user/repo.git'
];

$cmd = $processor->process('git', $args);
// Result: git remote add --track --end-of-options origin git@github.com:user/repo.git
```

--------------------------------

### Initialize Git Class

Source: https://github.com/czproject/git-php/blob/master/_autodocs/configuration.md

Constructor signature for the Git class.

```php
public function __construct(?IRunner $runner = NULL)
```

--------------------------------

### GitRepository Constructor

Source: https://github.com/czproject/git-php/blob/master/_autodocs/api-reference/GitRepository.md

Initializes a new GitRepository instance for a specific directory.

```APIDOC
## Constructor

### Description
Initializes a new instance of the GitRepository class for the specified repository path.

### Signature
`public function __construct(string $repository, ?IRunner $runner = NULL)`

### Parameters
- **repository** (string) - Required - Absolute path to repository directory or .git directory.
- **runner** (IRunner|NULL) - Optional - Custom runner implementation. Defaults to CliRunner.

### Throws
- **GitException** - If repository path is not found.
```

--------------------------------

### Handle InvalidStateException

Source: https://github.com/czproject/git-php/blob/master/_autodocs/errors.md

Demonstrates catching an InvalidStateException when a MemoryRunner is used without proper test result setup.

```php
try {
    $runner = new CzProject\GitPhp\Runners\MemoryRunner('/test');
    // Missing: $runner->setResult(...);
    $result = $runner->run('/test', ['status']);
} catch (CzProject\GitPhp\InvalidStateException $e) {
    echo "Missing test setup: " . $e->getMessage();
}

// Test setup pattern
$runner = new CzProject\GitPhp\Runners\MemoryRunner('/test');
$runner->setResult(['branch'], [], "* master\n  develop");
$result = $runner->run('/test', ['branch']); // Now works
```

--------------------------------

### Process Git Command with Options

Source: https://github.com/czproject/git-php/blob/master/_autodocs/api-reference/CommandProcessor.md

Demonstrates passing options and flags as associative arrays to the processor.

```php
$cmd = $processor->process('git', [
    'commit',
    ['-m' => 'Fix bug'],
    ['--no-verify' => true],
]);
// Unix: git commit -m 'Fix bug' --no-verify
// Windows: git commit -m "Fix bug" --no-verify
```

--------------------------------

### Get current branch name in PHP

Source: https://github.com/czproject/git-php/blob/master/_autodocs/api-reference/GitRepository.md

Returns the name of the currently checked out branch without the remote prefix.

```php
$branch = $repo->getCurrentBranchName();
echo $branch; // 'master'
```

--------------------------------

### Handle Missing Repository Exception

Source: https://github.com/czproject/git-php/blob/master/_autodocs/errors.md

Demonstrates catching a GitException when opening a non-existent repository and initializing a new one as a fallback.

```php
try {
    $repo = $git->open('/nonexistent/path');
} catch (CzProjectitPhpitException $e) {
    // Initialize a new repository instead
    $repo = $git->init('/nonexistent/path');
}
```

--------------------------------

### Configure Production Git Access

Source: https://github.com/czproject/git-php/blob/master/_autodocs/configuration.md

Initialize the Git client using either the default system runner or a custom CLI path.

```php
// Use system git with defaults
$git = new CzProject\GitPhp\Git;

// Open repository
$repo = $git->open('/var/www/project');

// Or open with custom runner
$runner = new CzProject\GitPhp\Runners\CliRunner('/usr/bin/git');
$git = new CzProject\GitPhp\Git($runner);
$repo = $git->open('/var/www/project');
```

--------------------------------

### Initialize CommandProcessor in a Runner

Source: https://github.com/czproject/git-php/blob/master/_autodocs/api-reference/CommandProcessor.md

Demonstrates integrating CommandProcessor within a custom runner implementation.

```php
// In CliRunner
class CliRunner implements IRunner
{
    private $commandProcessor;

    public function __construct($gitBinary = 'git')
    {
        $this->commandProcessor = new CommandProcessor;
    }

    public function run($cwd, array $args, ?array $env = NULL)
    {
        $command = $this->commandProcessor->process($this->gitBinary, $args);
        // Execute $command via proc_open()
    }
}
```

--------------------------------

### Define Command Options

Source: https://github.com/czproject/git-php/blob/master/_autodocs/README.md

Demonstrates the supported formats for command options, including strings, booleans, and arrays.

```php
// Command options - various formats supported
array $options = [
    '-m' => 'message',           // String value
    '--force' => true,           // Boolean flag
    '--verify' => false,         // Omitted boolean
    '-q' => NULL,               // Omitted option
    ['file1', 'file2'],         // Array of values
];
```

--------------------------------

### Initialize Git Class

Source: https://github.com/czproject/git-php/blob/master/_autodocs/api-reference/Git.md

Instantiate the Git class using either the default CliRunner or a custom runner implementation.

```php
// Using default CliRunner
$git = new CzProject\GitPhp\Git;

// Using custom runner
$runner = new CzProject\GitPhp\Runners\MemoryRunner('/path/to/repo');
$git = new CzProject\GitPhp\Git($runner);
```

--------------------------------

### GitRepository::__construct

Source: https://github.com/czproject/git-php/blob/master/_autodocs/configuration.md

Initializes a new GitRepository instance by specifying the repository path and an optional custom runner.

```APIDOC
## GitRepository::__construct

### Description
Initializes a new GitRepository instance. The repository path is normalized by stripping the .git suffix and converting it to an absolute path.

### Signature
`public function __construct(string $repository, ?IRunner $runner = NULL)`

### Parameters
- **repository** (string) - Required - Repository path. Can end with .git or be a directory containing .git.
- **runner** (IRunner|NULL) - Optional - Custom runner. NULL defaults to CliRunner.

### Exceptions
- Throws `GitException` if the provided path does not exist.
```

--------------------------------

### Initialize CommandProcessor

Source: https://github.com/czproject/git-php/blob/master/_autodocs/api-reference/CommandProcessor.md

Constructor signature for the CommandProcessor class.

```php
public function __construct($mode = self::MODE_DETECT)
```

--------------------------------

### Retrieve standard output as lines in PHP

Source: https://github.com/czproject/git-php/blob/master/_autodocs/api-reference/RunnerResult.md

Use getOutput to iterate over command output line by line.

```php
$result = $repo->run('branch', '-a');
$lines = $result->getOutput();
foreach ($lines as $branch) {
    echo "Branch: $branch\n";
}
```

--------------------------------

### Work with Branches

Source: https://github.com/czproject/git-php/blob/master/_autodocs/README.md

Manages branch creation, switching, and merging.

```php
$repo->createBranch('feature-x', TRUE);  // Create and checkout
$repo->checkout('master');
$repo->merge('feature-x');
```

--------------------------------

### CzProject\GitPhp\Git::__construct

Source: https://github.com/czproject/git-php/blob/master/_autodocs/configuration.md

Initializes the Git library instance. Allows for dependency injection of a custom command runner.

```APIDOC
## public function __construct(?IRunner $runner = NULL)

### Description
Initializes the Git library. If no runner is provided, it defaults to using the system's 'git' binary via CliRunner.

### Parameters
- **runner** (IRunner|NULL) - Optional - Custom command execution backend. Defaults to NULL (uses CliRunner).
```

--------------------------------

### Production Usage

Source: https://github.com/czproject/git-php/blob/master/_autodocs/api-reference/IRunner.md

Default implementation using CliRunner to execute real git commands.

```php
// Default CliRunner - executes real git commands
$git = new CzProject\GitPhp\Git;
$repo = $git->open('/production/repo');
```

--------------------------------

### Initialize and Configure MemoryRunner

Source: https://github.com/czproject/git-php/blob/master/_autodocs/api-reference/IRunner.md

Constructor and result configuration for the in-memory test runner.

```php
namespace CzProject\GitPhp\Runners;

class MemoryRunner implements IRunner
{
    public function __construct($cwd)
    public function setResult(array $args, array $env, $output, $errorOutput = [], $exitCode = 0): self
}
```

```php
$runner = new MemoryRunner('/path/to/repo');

// Set up expected command results
$runner->setResult(
    ['branch', '-a'],
    [],
    "* master\n  origin/master\n  feature-x"
);

$runner->setResult(
    ['status', '--porcelain'],
    [],
    "M file.txt\nA newfile.txt"
);

// Use with Git class
$git = new CzProject\GitPhp\Git($runner);
$repo = $git->open('/path/to/repo');

// Commands will return the predefined results
$branches = $repo->getBranches(); // Returns defined result
$hasChanges = $repo->hasChanges(); // TRUE (has output)
```

--------------------------------

### Process Git Command with Multiple Arguments

Source: https://github.com/czproject/git-php/blob/master/_autodocs/api-reference/CommandProcessor.md

Shows how to handle complex command structures including flags and positional arguments.

```php
$cmd = $processor->process('git', [
    'clone',
    ['-q' => true],
    '--end-of-options',
    'https://github.com/user/repo.git',
    '/path/to/clone'
]);
// Unix: git clone -q --end-of-options https://github.com/user/repo.git '/path/to/clone'
```

--------------------------------

### Stage All Changes

Source: https://github.com/czproject/git-php/blob/master/_autodocs/api-reference/GitRepository.md

Stage all created, modified, and removed files using addAllChanges.

```php
$repo->addAllChanges()->commit('Update all changes');
```

--------------------------------

### Execute Basic Git Operations

Source: https://github.com/czproject/git-php/blob/master/readme.md

Manage repository state, file staging, renaming, and removal.

```php
$repo->hasChanges();    // returns boolean
$repo->commit('commit message');
$repo->merge('branch-name');
$repo->checkout('master');

$repo->getRepositoryPath();

// adds files into commit
$repo->addFile('file.txt');
$repo->addFile('file1.txt', 'file2.txt');
$repo->addFile(['file3.txt', 'file4.txt']);

// renames files in repository
$repo->renameFile('old.txt', 'new.txt');
$repo->renameFile([
    'old1.txt' => 'new1.txt',
    'old2.txt' => 'new2.txt',
]);

// removes files from repository
$repo->removeFile('file.txt');
$repo->removeFile('file1.txt', 'file2.txt');
$repo->removeFile(['file3.txt', 'file4.txt']);

// adds all changes in repository
$repo->addAllChanges();
```

--------------------------------

### Handle command execution results

Source: https://github.com/czproject/git-php/blob/master/_autodocs/types.md

Demonstrates checking the success of a command and retrieving its output.

```php
$result = $repo->run('status');
if ($result->isOk()) {
    $lines = $result->getOutput();
}
```

--------------------------------

### IRunner::run()

Source: https://github.com/czproject/git-php/blob/master/_autodocs/api-reference/IRunner.md

Executes a git command and returns the result.

```APIDOC
## run($cwd, $args, $env)

### Description
Executes a git command and returns the result.

### Parameters
- **cwd** (string) - Required - Current working directory for command execution.
- **args** (array) - Required - Command arguments as array.
- **env** (array|NULL) - Optional - Environment variables to set for the command.

### Returns
- **RunnerResult** - Command execution result with output and exit code.
```

--------------------------------

### Project File Structure

Source: https://github.com/czproject/git-php/blob/master/_autodocs/INDEX.md

Visual representation of the project directory layout.

```text
output/
├── README.md                    # Start here
├── INDEX.md                     # This file
├── MANIFEST.txt                 # Coverage summary
├── types.md                     # Type reference
├── errors.md                    # Exception reference
├── configuration.md             # Configuration reference
└── api-reference/               # Class documentation
    ├── Git.md
    ├── GitRepository.md
    ├── Commit.md
    ├── CommitId.md
    ├── RunnerResult.md
    ├── IRunner.md
    ├── CommandProcessor.md
    └── Helpers.md
```

--------------------------------

### Implement Custom Runner

Source: https://github.com/czproject/git-php/blob/master/_autodocs/README.md

Create a custom command execution runner by implementing the IRunner interface.

```php
class CustomRunner implements CzProject\GitPhp\IRunner
{
    public function run($cwd, array $args, ?array $env = NULL): CzProject\GitPhp\RunnerResult
    {
        // Custom execution logic
    }

    public function getCwd(): string
    {
        return getcwd();
    }
}

$git = new CzProject\GitPhp\Git(new CustomRunner);
```

--------------------------------

### MemoryRunner::__construct

Source: https://github.com/czproject/git-php/blob/master/_autodocs/configuration.md

Initializes a new instance of the MemoryRunner with a specified working directory.

```APIDOC
## MemoryRunner::__construct

### Description
Initializes the MemoryRunner with the working directory for the simulated repository.

### Parameters
- **cwd** (string) - Required - Working directory for this runner.
```

--------------------------------

### Checkout a branch in PHP

Source: https://github.com/czproject/git-php/blob/master/_autodocs/api-reference/GitRepository.md

Switches the repository to the specified branch.

```php
$repo->checkout('develop');
$repo->checkout('feature-branch');
```

--------------------------------

### Retrieve standard output as a string in PHP

Source: https://github.com/czproject/git-php/blob/master/_autodocs/api-reference/RunnerResult.md

Use getOutputAsString to obtain the full command output as a single joined string.

```php
$result = $repo->run('status');
echo $result->getOutputAsString();
```

--------------------------------

### Open Existing Repository

Source: https://github.com/czproject/git-php/blob/master/_autodocs/api-reference/Git.md

Access an existing local Git repository by providing its directory path.

```php
$git = new CzProject\GitPhp\Git;
$repo = $git->open('/var/www/my-project');
```

--------------------------------

### Process Arguments with Spaces

Source: https://github.com/czproject/git-php/blob/master/_autodocs/api-reference/CommandProcessor.md

Demonstrates how the processor handles arguments containing spaces with platform-specific escaping.

```php
$cmd = $processor->process('git', ['commit', ['-m' => 'My commit message']]);
// Unix: git commit -m 'My commit message'
// Windows: git commit -m "My commit message"
```

--------------------------------

### Project Source Structure

Source: https://github.com/czproject/git-php/blob/master/_autodocs/README.md

Overview of the file and module organization within the src directory.

```text
src/
├── Git.php                 — Main entry point
├── GitRepository.php       — Repository operations
├── Commit.php             — Commit value object
├── CommitId.php           — Commit ID type
├── IRunner.php            — Execution interface
├── RunnerResult.php       — Result object
├── CommandProcessor.php   — Command building
├── Helpers.php            — Utility functions
├── exceptions.php         — Exception classes
└── Runners/
    ├── CliRunner.php      — System command execution
    ├── MemoryRunner.php   — Test runner
    └── OldGitRunner.php   — Legacy compatibility
```

--------------------------------

### Manage Git Remotes and Syncing

Source: https://github.com/czproject/git-php/blob/master/readme.md

Methods for pulling, pushing, fetching, and managing remote repository configurations.

```php
// pulls changes from remote
$repo->pull('remote-name', ['--options']);
$repo->pull('origin');

// pushs changes to remote
$repo->push('remote-name', ['--options']);
$repo->push('origin');
$repo->push(['origin', 'master'], ['-u']);

// fetchs changes from remote
$repo->fetch('remote-name', ['--options']);
$repo->fetch('origin');
$repo->fetch(['origin', 'master']);

// adds remote repository
$repo->addRemote('remote-name', 'repository-url', ['--options']);
$repo->addRemote('origin', 'git@github.com:czproject/git-php.git');

// renames remote
$repo->renameRemote('old-remote-name', 'new-remote-name');
$repo->renameRemote('origin', 'upstream');

// removes remote
$repo->removeRemote('remote-name');
$repo->removeRemote('origin');

// changes remote URL
$repo->setRemoteUrl('remote-name', 'new-repository-url');
$repo->setRemoteUrl('upstream', 'https://github.com/czproject/git-php.git');
```

--------------------------------

### Use CommitId for validation and instantiation

Source: https://github.com/czproject/git-php/blob/master/_autodocs/types.md

Demonstrates how to instantiate a CommitId and validate a hash string.

```php
$id = new CzProject\GitPhp\CommitId('734713bc047d87bf7eac9674765ae793478c50d3');
echo (string) $id;

if (CzProject\GitPhp\CommitId::isValid($hash)) {
    $id = new CzProject\GitPhp\CommitId($hash);
}
```

--------------------------------

### open($directory)

Source: https://github.com/czproject/git-php/blob/master/_autodocs/api-reference/Git.md

Opens an existing Git repository directory for manipulation.

```APIDOC
## open($directory)

### Description
Opens an existing Git repository directory for manipulation.

### Parameters
#### Path Parameters
- **directory** (string) - Required - Absolute or relative path to the repository directory.

### Returns
- **GitRepository** - Repository object for executing git operations.

### Throws
- **GitException** - Repository path not found (realpath fails).
```

--------------------------------

### Run git commands with run()

Source: https://github.com/czproject/git-php/blob/master/_autodocs/api-reference/GitRepository.md

Use this method to execute git commands and receive a RunnerResult object containing the full execution details. This includes the exit code, error output, and standard output.

```php
$result = $repo->run('status', '--porcelain');
echo $result->getCommand();
echo $result->getExitCode();
$lines = $result->getOutput();
```

--------------------------------

### execute(...$cmd)

Source: https://github.com/czproject/git-php/blob/master/_autodocs/api-reference/GitRepository.md

Executes a git command and returns the output as an array of lines.

```APIDOC
## execute(...$cmd)

### Description
Executes a git command and returns the output as an array of lines.

### Signature
`public function execute(...$cmd): string[]`

### Parameters
- **...cmd** (mixed) - Required - Command parts as variadic arguments.

### Returns
- **string[]** - Command output as array of lines.

### Throws
- **GitException** - If the git command fails.

### Example
```php
$output = $repo->execute('remote', 'set-branches', 'origin', 'main');
```
```

--------------------------------

### Implement Custom Runner

Source: https://github.com/czproject/git-php/blob/master/_autodocs/api-reference/IRunner.md

Create a custom runner by implementing the IRunner interface and passing it to the Git constructor.

```php
class CustomRunner implements \CzProject\GitPhp\IRunner
{
    public function run($cwd, array $args, ?array $env = NULL): \CzProject\GitPhp\RunnerResult
    {
        // Your custom command execution logic here
        // Must return a RunnerResult object
        
        $command = ''; // Build command string
        $exitCode = 0; // Execute and get exit code
        $output = '';  // Capture output
        $errorOutput = ''; // Capture error output
        
        return new \CzProject\GitPhp\RunnerResult(
            $command,
            $exitCode,
            $output,
            $errorOutput
        );
    }

    public function getCwd(): string
    {
        return getcwd();
    }
}

// Use custom runner
$runner = new CustomRunner;
$git = new CzProject
GitPhp\Git($runner);
```

--------------------------------

### Git Repository Lifecycle

Source: https://github.com/czproject/git-php/blob/master/_autodocs/README.md

Methods for initializing, cloning, and opening Git repositories using the Git class.

```APIDOC
## Git::init

### Description
Initializes a new Git repository at the specified path.

### Method
public function init(string $path): GitRepository

## Git::cloneRepository

### Description
Clones a remote repository to a local directory.

### Method
public function cloneRepository(string $url, string $directory): GitRepository

## Git::open

### Description
Opens an existing Git repository at the specified path.

### Method
public function open(string $path): GitRepository
```

--------------------------------

### run(...$args)

Source: https://github.com/czproject/git-php/blob/master/_autodocs/api-reference/GitRepository.md

Executes a git command and returns the full RunnerResult object containing output, errors, and exit code.

```APIDOC
## run(...$args)

### Description
Executes a git command and returns the full RunnerResult object.

### Signature
`public function run(...$args): RunnerResult`

### Parameters
- **...args** (mixed) - Required - Command parts as variadic arguments.

### Returns
- **RunnerResult** - Full command execution result including output, errors, and exit code.

### Throws
- **GitException** - If the git command fails.

### Example
```php
$result = $repo->run('status', '--porcelain');
echo $result->getExitCode();
```
```

--------------------------------

### Configure CliRunner Process Execution

Source: https://github.com/czproject/git-php/blob/master/_autodocs/configuration.md

Internal configuration for proc_open used by CliRunner.

```php
$descriptorspec = [
    0 => ['pipe', 'r'], // stdin
    1 => ['pipe', 'w'], // stdout
    2 => ['pipe', 'w'], // stderr
];

$process = proc_open($command, $descriptorspec, $pipes, $cwd, $env, [
    'bypass_shell' => TRUE,
]);
```

--------------------------------

### Manage Repository Branches

Source: https://github.com/czproject/git-php/blob/master/readme.md

List, create, and remove branches within the repository.

```php
// gets list of all repository branches (remotes & locals)
$repo->getBranches();

// gets list of all local branches
$repo->getLocalBranches();

// gets name of current branch
$repo->getCurrentBranchName();

// creates new branch
$repo->createBranch('new-branch');

// creates new branch and checkout
$repo->createBranch('patch-1', TRUE);

// removes branch
$repo->removeBranch('branch-name');
```

--------------------------------

### Manage Repository Tags

Source: https://github.com/czproject/git-php/blob/master/readme.md

List, create, rename, and remove tags.

```php
// gets list of all tags in repository
$repo->getTags();

// creates new tag
$repo->createTag('v1.0.0');
$repo->createTag('v1.0.0', $options);
$repo->createTag('v1.0.0', [
	'-m' => 'message',
]);

// renames tag
$repo->renameTag('old-tag-name', 'new-tag-name');

// removes tag
$repo->removeTag('tag-name');
```

--------------------------------

### Configure Testing with MemoryRunner

Source: https://github.com/czproject/git-php/blob/master/_autodocs/configuration.md

Use MemoryRunner to define deterministic command results for unit testing without external dependencies.

```php
// Create test runner with predefined results
$runner = new CzProject\GitPhp\Runners\MemoryRunner('/test/repo');
$runner->setResult(['status'], [], 'On branch master')
       ->setResult(['branch', '-a'], [], "* master\n  develop")
       ->setResult(['log', '-1', '--format=%H'], [], 'abc123');

// Use in tests
$git = new CzProject\GitPhp\Git($runner);
$repo = $git->open('/test/repo');

// Results are deterministic and reproducible
```

--------------------------------

### Process Simple Arguments

Source: https://github.com/czproject/git-php/blob/master/_autodocs/api-reference/CommandProcessor.md

Basic usage of the process method for simple command arguments.

```php
$processor = new CommandProcessor;
$cmd = $processor->process('git', ['commit', '--all']);
// Output: git commit --all
```

--------------------------------

### Clone repositories with automatic directory naming

Source: https://github.com/czproject/git-php/blob/master/_autodocs/api-reference/Helpers.md

Simplify directory organization by allowing the library to automatically determine the destination directory name from the repository URL.

```php
// Clone multiple repositories with automatic naming
$git = new CzProject\GitPhp\Git;

$repositories = [
    'https://github.com/user/frontend.git',
    'https://github.com/user/backend.git',
    'https://github.com/user/cli-tools.git',
];

foreach ($repositories as $url) {
    // Auto-extracts and uses directory name
    $repo = $git->cloneRepository($url);
    // Creates: ./frontend, ./backend, ./cli-tools
}
```

--------------------------------

### Add a remote repository

Source: https://github.com/czproject/git-php/blob/master/_autodocs/api-reference/GitRepository.md

Adds a new remote with a specified name and URL. Throws a GitException on failure.

```php
$repo->addRemote('origin', 'https://github.com/user/project.git');
$repo->addRemote('upstream', 'git@github.com:upstream/project.git');
```

--------------------------------

### Retrieve and display commit metadata in PHP

Source: https://github.com/czproject/git-php/blob/master/_autodocs/api-reference/Commit.md

Demonstrates opening a repository and accessing various commit properties such as author, committer, and message body.

```php
$git = new CzProject\GitPhp\Git;
$repo = $git->open('/path/to/repo');

// Get last commit
$commit = $repo->getLastCommit();

// Access all metadata
echo "Commit ID: " . $commit->getId() . "\n";
echo "Subject: " . $commit->getSubject() . "\n";
echo "Author: " . $commit->getAuthorName() . " <" . $commit->getAuthorEmail() . ">\n";
echo "Author Date: " . $commit->getAuthorDate()->format('Y-m-d H:i:s') . "\n";
echo "Committer: " . $commit->getCommitterName() . " <" . $commit->getCommitterEmail() . ">\n";
echo "Committer Date: " . $commit->getCommitterDate()->format('Y-m-d H:i:s') . "\n";

if ($commit->getBody()) {
    echo "Message Body:\n" . $commit->getBody() . "\n";
}

// Get specific commit by ID
$specificCommit = $repo->getCommit('734713bc047d87bf7eac9674765ae793478c50d3');
echo $specificCommit->getSubject();
```

--------------------------------

### Constructor Definition

Source: https://github.com/czproject/git-php/blob/master/_autodocs/api-reference/RunnerResult.md

Defines the structure for initializing a new RunnerResult instance.

```php
public function __construct(
    string $command,
    int $exitCode,
    string|string[] $output,
    string|string[] $errorOutput
)
```

--------------------------------

### Extend Git-PHP with Custom Methods

Source: https://github.com/czproject/git-php/blob/master/readme.md

Create custom Git and Repository classes to add project-specific functionality.

```php
class OwnGit extends \CzProject\GitPhp\Git
{
	public function open($directory)
	{
		return new OwnGitRepository($directory, $this->runner);
	}
}

class OwnGitRepository extends \CzProject\GitPhp\GitRepository
{
	public function setRemoteBranches($name, array $branches)
	{
		$this->run('remote', 'set-branches', $name, $branches);
		return $this;
	}
}


$git = new OwnGit;
$repo = $git->open('/path/to/repo');
$repo->addRemote('origin', 'repository-url');
$repo->setRemoteBranches('origin', [
	'branch-1',
	'branch-2',
]);
```

--------------------------------

### Create a new branch in PHP

Source: https://github.com/czproject/git-php/blob/master/_autodocs/api-reference/GitRepository.md

Use to create a new branch, with an optional parameter to automatically check it out.

```php
// Create branch without checking out
$repo->createBranch('feature-x');

// Create and immediately checkout
$repo->createBranch('feature-x', TRUE);
```

--------------------------------

### Process command with environment variables

Source: https://github.com/czproject/git-php/blob/master/_autodocs/api-reference/CommandProcessor.md

Prepends environment variables to the generated command string.

```php
$env = [
    'GIT_AUTHOR_NAME' => 'John Doe',
    'GIT_AUTHOR_EMAIL' => 'john@example.com',
];

$cmd = $processor->process('git', ['commit', ['-m' => 'test']], $env);
```

--------------------------------

### getOutput()

Source: https://github.com/czproject/git-php/blob/master/_autodocs/api-reference/RunnerResult.md

Returns the standard output as an array of lines.

```APIDOC
## getOutput()

### Description
Returns the standard output as an array of lines, normalized for line endings.

### Returns
- **string[]** - Output split into lines.
```

--------------------------------

### Create a Git tag

Source: https://github.com/czproject/git-php/blob/master/_autodocs/api-reference/GitRepository.md

Creates a new tag in the repository. Supports both lightweight and annotated tags via the options parameter.

```php
// Lightweight tag
$repo->createTag('v1.0.0');

// Annotated tag with message
$repo->createTag('v1.0.0', ['-m' => 'Release version 1.0.0']);
```

--------------------------------

### Composer Autoloading Configuration

Source: https://github.com/czproject/git-php/blob/master/_autodocs/README.md

Configure classmap autoloading in composer.json for the source directory.

```json
// composer.json uses classmap autoloading
"autoload": {
    "classmap": ["src/"]
}
```

--------------------------------

### Implement Custom Logging Runner

Source: https://github.com/czproject/git-php/blob/master/_autodocs/configuration.md

Create a decorator for IRunner to intercept and log git commands before execution.

```php
class LoggingRunner implements CzProject\GitPhp\IRunner
{
    private $inner;

    public function __construct(CzProject\GitPhp\IRunner $inner)
    {
        $this->inner = $inner;
    }

    public function run($cwd, array $args, ?array $env = NULL): CzProject\GitPhp\RunnerResult
    {
        error_log("Running git command: " . implode(' ', $args));
        return $this->inner->run($cwd, $args, $env);
    }

    public function getCwd(): string
    {
        return $this->inner->getCwd();
    }
}

// Use with logging
$baseRunner = new CzProject\GitPhp\Runners\CliRunner;
$loggingRunner = new LoggingRunner($baseRunner);
$git = new CzProject\GitPhp\Git($loggingRunner);
```

--------------------------------

### Handle File Not Found on Add

Source: https://github.com/czproject/git-php/blob/master/_autodocs/errors.md

Retrieves the list of tracked files when an add operation fails due to a missing file.

```php
try {
    $repo->addFile('long-deleted-file.txt');
} catch (CzProjectitPhpitException $e) {
    echo "File not found: " . $e->getMessage();
    // Check what files actually exist
    $existing = $repo->run('ls-files');
    echo "Tracked files: " . implode(', ', $existing->getOutput());
}
```

--------------------------------

### Handling Runner Result Details

Source: https://github.com/czproject/git-php/blob/master/_autodocs/errors.md

Extract detailed command, exit code, and error output from a GitException.

```php
try {
    $repo->push('origin');
} catch (CzProject\GitPhp\GitException $e) {
    $result = $e->getRunnerResult();
    if ($result) {
        error_log(sprintf(
            "Git push failed\nCommand: %s\nExit Code: %d\nError: %s",
            $result->getCommand(),
            $result->getExitCode(),
            $result->getErrorOutputAsString()
        ));
    } else {
        error_log("Git push failed: " . $e->getMessage());
    }
}
```

--------------------------------

### Simulate command failure with MemoryRunner

Source: https://github.com/czproject/git-php/blob/master/_autodocs/errors.md

Use MemoryRunner to mock command execution results and verify error handling logic in PHP.

```php
$runner = new CzProject\GitPhp\Runners\MemoryRunner('/test');

// Simulate command failure
$runner->setResult(
    ['clone', '--end-of-options', 'invalid-url', '/test/repo'],
    [],
    '', // output
    'fatal: repository not found',  // stderr
    128  // exit code
);

try {
    $result = $runner->run('/test', ['clone', '--end-of-options', 'invalid-url', '/test/repo']);
    // Check result status
    if (!$result->isOk()) {
        echo "Clone failed as expected";
    }
} catch (Exception $e) {
    echo "Exception caught";
}
```

--------------------------------

### Instantiate CommitId

Source: https://github.com/czproject/git-php/blob/master/_autodocs/api-reference/CommitId.md

Create a new CommitId instance or handle invalid input via exceptions.

```php
$commitId = new CzProject\GitPhp\CommitId('734713bc047d87bf7eac9674765ae793478c50d3');

// Invalid ID throws exception
try {
    $invalidId = new CzProject\GitPhp\CommitId('invalid');
} catch (CzProject\GitPhp\InvalidArgumentException $e) {
    echo "Invalid commit ID";
}
```

--------------------------------

### addAllChanges()

Source: https://github.com/czproject/git-php/blob/master/_autodocs/api-reference/GitRepository.md

Stages all changes in the repository.

```APIDOC
## addAllChanges()

### Description
Stages all created, modified, and removed files using git add --all.

### Signature
`public function addAllChanges(): static`

### Returns
- **static** - Returns $this for method chaining.

### Throws
- **GitException** - If git command fails.
```

--------------------------------

### Stage Files

Source: https://github.com/czproject/git-php/blob/master/_autodocs/api-reference/GitRepository.md

Stage files for commit using addFile. Supports single strings, multiple arguments, or arrays, and allows method chaining.

```php
// Add single file
$repo->addFile('readme.md');

// Add multiple files with arguments
$repo->addFile('file1.txt', 'file2.txt');

// Add array of files
$repo->addFile(['file1.txt', 'file2.txt', 'file3.txt']);

// Chaining
$repo->addFile('file.txt')->commit('Add file');
```

--------------------------------

### createBranch($name, $checkout = FALSE)

Source: https://github.com/czproject/git-php/blob/master/_autodocs/api-reference/GitRepository.md

Creates a new branch, with an optional parameter to automatically check it out.

```APIDOC
## createBranch($name, $checkout = FALSE)

### Description
Creates a new branch, optionally checking it out.

### Parameters
- **name** (string) - Required - Branch name to create.
- **checkout** (bool) - Optional - If TRUE, automatically checks out the new branch.

### Returns
- **static** - Returns $this for method chaining.

### Throws
- **GitException** - If git branch fails.
```

--------------------------------

### Clone Repository

Source: https://github.com/czproject/git-php/blob/master/_autodocs/README.md

Clones an existing remote repository to a local directory.

```php
$repo = $git->cloneRepository('https://github.com/user/repo.git', '/path/to/clone');
```

--------------------------------

### Process command with array arguments

Source: https://github.com/czproject/git-php/blob/master/_autodocs/api-reference/CommandProcessor.md

Arrays provided as arguments are flattened into the command string.

```php
$files = ['file1.txt', 'file2.txt', 'file3.txt'];
$cmd = $processor->process('git', ['add', $files]);
// Output: git add file1.txt file2.txt file3.txt
```

--------------------------------

### addFile()

Source: https://github.com/czproject/git-php/blob/master/_autodocs/api-reference/GitRepository.md

Stages files for commit.

```APIDOC
## addFile()

### Description
Stages file(s) for commit using git add.

### Signature
`public function addFile(string|string[] $file): static`

### Parameters
- **file** (string|string[]) - Required - Single file path, multiple arguments, or array of file paths relative to repository root.

### Returns
- **static** - Returns $this for method chaining.

### Throws
- **GitException** - If file path does not exist or git command fails.
```

--------------------------------

### Handle Library Exceptions

Source: https://github.com/czproject/git-php/blob/master/_autodocs/types.md

Catching the base library exception during repository operations.

```php
try {
    $repo = $git->open('/invalid/path');
} catch (CzProject\GitPhp\Exception $e) {
    echo "Git operation failed: " . $e->getMessage();
}
```

--------------------------------

### Execute Custom Git Commands

Source: https://github.com/czproject/git-php/blob/master/readme.md

Run arbitrary Git commands using the execute method.

```php
$output = $repo->execute('command');
$output = $repo->execute('command', 'with', 'parameters');

// example:
$repo->execute('remote', 'set-branches', $originName, $branches);
```

--------------------------------

### getOutputAsString()

Source: https://github.com/czproject/git-php/blob/master/_autodocs/api-reference/RunnerResult.md

Returns the standard output as a single string.

```APIDOC
## getOutputAsString()

### Description
Returns the complete standard output as a single string with lines joined by newlines.

### Returns
- **string** - Complete output.
```

--------------------------------

### cloneRepository($url, $directory = NULL, ?array $params = NULL)

Source: https://github.com/czproject/git-php/blob/master/_autodocs/api-reference/Git.md

Clones a Git repository from a remote URL into a local directory.

```APIDOC
## cloneRepository($url, $directory = NULL, ?array $params = NULL)

### Description
Clones a Git repository from a remote URL into a local directory.

### Parameters
- **url** (string) - Required - Remote repository URL (HTTPS or SSH).
- **directory** (string|NULL) - Optional - Target directory path. If NULL, extracts name from URL.
- **params** (array|NULL) - Optional - Additional clone options. Defaults to '-q' for quiet mode.

### Returns
- **GitRepository** - Cloned repository object.

### Throws
- **GitException** - Repository already exists in target directory.
- **GitException** - Clone command fails (includes stderr in message).
```

--------------------------------

### Handle StaticClassException

Source: https://github.com/czproject/git-php/blob/master/_autodocs/types.md

Catching errors from attempting to instantiate static classes.

```php
try {
    $helpers = new CzProject\GitPhp\Helpers; // Static class only
} catch (CzProject\GitPhp\StaticClassException $e) {
    echo "Cannot instantiate static class";
}

// Correct usage
$isAbsolute = CzProject\GitPhp\Helpers::isAbsolute('/path');
```

--------------------------------

### Process command output

Source: https://github.com/czproject/git-php/blob/master/_autodocs/api-reference/RunnerResult.md

Execute a command and iterate through the output lines if the execution is successful.

```php
$git = new CzProject\GitPhp\Git;
$repo = $git->open('/path/to/repo');

// Execute raw command and process output
$result = $repo->run('branch', '-a');

if ($result->isOk()) {
    $branches = $result->getOutput();
    echo "Total branches: " . count($branches) . "\n";
    foreach ($branches as $branch) {
        echo "- " . trim(ltrim($branch, '*')) . "\n";
    }
} else {
    echo "Error: " . $result->getErrorOutputAsString();
}
```

--------------------------------

### Commit Changes to Repository

Source: https://github.com/czproject/git-php/blob/master/_autodocs/INDEX.md

Stages a file and commits changes to the repository.

```php
$repo->addFile('file.txt');
$repo->commit('Initial commit');
```
Tokens:
Raw