Git-PHP

Install the library using Composer. Ensure you have PHP 8.0 or later and that the git client is installed and available in your system's PATH.

composer require czproject/git-php

You can extend CzProject\GitPhp\Git and CzProject\GitPhp\GitRepository to add domain-specific methods. This allows you to wrap execute() calls into a clean, reusable API.

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->setRemoteBranches('origin', ['branch-1', 'branch-2']);

To interact with a Git repository, instantiate the CzProject\GitPhp\GitRepository class. You must provide the path to the repository. If the path points to a .git directory, the class will automatically resolve it to the parent directory.

By default, it uses CzProject\GitPhp\Runners\CliRunner to execute commands via the system CLI. You can provide a custom implementation of IRunner if needed.

use CzProject\GitPhp\GitRepository;

// Path to the repository folder
$repoPath = '/path/to/your/repo';
$repository = new GitRepository($repoPath);

When performing operations like push() that require authentication, use one of these strategies:

1. Use SSH: Use SSH URLs instead of HTTPS to leverage SSH keys.
2. Git Credential Storage: Configure Git to cache credentials on your system.
3. Embed credentials in URL: Use the format https://user:password@server/path/repo.git.
4. Use --repo flag for push: For push() operations, you can pass the authenticated URL via the --repo argument in the options array.

// Using the --repo argument to provide credentials during push
$git->push(NULL, ['--repo' => 'https://user:password@server/path/repo.git']);

If a specific Git command is not provided as a method in the library, you can use the execute() method to run any command directly on the repository.

// Basic command execution
$output = $repo->execute('command');

// Command with parameters
$output = $repo->execute('command', 'with', 'parameters');

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

Use the init() method on a CzProject\GitPhp\Git instance to create a new repository in a specified directory. You can pass an optional array of Git options, such as '--bare' to create a bare repository.

$git = new CzProject\GitPhp\Git;

// Initialize a standard repository
$repo = $git->init('/path/to/repo-directory');

// Initialize a bare repository
$repo = $git->init('/path/to/repo-directory', [
	'--bare',
]);

Interact with remote repositories using pull(), push(), fetch(), and remote management methods.

// Pull, Push, and Fetch
$repo->pull('origin');
$repo->pull('remote-name', ['--options']);

$repo->push('origin');
$repo->push(['origin', 'master'], ['-u']);

$repo->fetch('origin');
$repo->fetch(['origin', 'master']);

// Remote management
$repo->addRemote('origin', 'git@github.com:czproject/git-php.git');
$repo->renameRemote('origin', 'upstream');
$repo->removeRemote('origin');
$repo->setRemoteUrl('upstream', 'https://github.com/czproject/git-php.git');

The GitRepository object provides methods for common Git tasks including adding files, committing, merging, and checking out branches.

// Check for changes
$repo->hasChanges();

// Add files to the staging area
$repo->addFile('file.txt');
$repo->addFile('file1.txt', 'file2.txt');
$repo->addFile(['file3.txt', 'file4.txt']);
$repo->addAllChanges();

// Commit changes
$repo->commit('commit message');

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

// Remove files
$repo->removeFile('file.txt');
$repo->removeFile(['file1.txt', 'file2.txt']);

// Branch and Merge
$repo->merge('branch-name');
$repo->checkout('master');

// Get repository path
$path = $repo->getRepositoryPath();

Use cloneRepository() to clone a remote repository. If you provide only the URL, it clones into a subdirectory named after the repository in the current working directory. To specify a custom destination, provide the path as the second argument.

$git = new CzProject\GitPhp\Git;

// Clone into a subdirectory 'git-php' in the current directory
$repo = $git->cloneRepository('https://github.com/czproject/git-php.git');

// Clone into a specific directory
$repo = $git->cloneRepository('https://github.com/czproject/git-php.git', '/path/to/my/subdir');

Manage local and remote branches using the following methods on a GitRepository instance:

// List branches
$allBranches = $repo->getBranches(); // includes remotes & locals
$localBranches = $repo->getLocalBranches();

// Current branch info
$currentName = $repo->getCurrentBranchName();

// Create and remove branches
$repo->createBranch('new-branch');
$repo->createBranch('patch-1', TRUE); // creates and checks out
$repo->removeBranch('branch-name');

Access commit data and history using getLastCommit() or getCommit($id). The returned commit object provides metadata about the author, committer, and message.

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

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

// Access commit metadata
$id = $commit->getId(); // Returns CommitId instance or can be cast to string
$subject = $commit->getSubject();
$body = $commit->getBody();
$authorName = $commit->getAuthorName();
$authorEmail = $commit->getAuthorEmail();
$authorDate = $commit->getAuthorDate();
$committerName = $commit->getCommitterName();
$committerEmail = $commit->getCommitterEmail();
$committerDate = $commit->getCommitterDate();
$date = $commit->getDate();

// Get last commit ID specifically
$lastId = $repo->getLastCommitId();

Use the following methods to manage tags within the repository:

// List tags
$tags = $repo->getTags();

// Create tags
$repo->createTag('v1.0.0');
$repo->createTag('v1.0.0', ['-m' => 'message']);

// Rename and remove tags
$repo->renameTag('old-tag-name', 'new-tag-name');
$repo->removeTag('tag-name');