Git Php Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require bit3/git-php
   

   Add to composer.json if not using autoloading:

   "autoload": {
       "psr-4": {
           "App\\": "app/",
           "Bit3\\Git\\": "vendor/bit3/git-php/src/"
       }
   }
   

   Run composer dump-autoload.

2. First Use Case: Cloning a Repository

   use Bit3\Git\Git;
   
   $git = new Git('/path/to/local/repo');
   $git->clone('https://github.com/user/repo.git');
   

3. Key Entry Points

   • Git::__construct(string $path): Initialize with a local repo path.
   • Git::clone(string $url): Clone a remote repo.
   • Git::pull(): Fetch and merge remote changes.
   • Git::commit(string $message): Commit staged changes.

4. Where to Look First

   • Git Class Docs (if available).
   • Examples (if provided).
   • Bit3\Git\Git namespace for core methods.

Implementation Patterns

Common Workflows

1. Repository Management

// Initialize and clone
$git = new Git('/tmp/repo');
$git->clone('https://github.com/laravel/laravel.git');

// Check status
$status = $git->status(); // Returns array of changed files

2. Branch Handling

// Create and switch branches
$git->branchCreate('feature/login');
$git->branchCheckout('feature/login');

// Merge branches
$git->branchMerge('main');

3. Commit and Push Workflow

$git->add('path/to/file');
$git->commit('Update login logic');
$git->push('origin', 'feature/login');

4. Tagging Releases

$git->tagCreate('v1.0.0', 'Release 1.0.0');
$git->push('origin', null, null, ['--tags']);

5. Integration with Laravel Artisan

Create a custom Artisan command:

namespace App\Console\Commands;

use Bit3\Git\Git;
use Illuminate\Console\Command;

class DeployCommand extends Command
{
    protected $signature = 'deploy:pull';
    public function handle()
    {
        $git = new Git(base_path());
        $git->pull();
        $this->info('Repository updated!');
    }
}

Integration Tips

• Error Handling: Wrap Git operations in try-catch blocks:

  try {
      $git->pull();
  } catch (\Bit3\Git\Exception $e) {
      Log::error('Git error: ' . $e->getMessage());
  }
  

• Logging: Use Laravel’s logging to track Git operations:

  $git->add('file.txt');
  Log::debug('Added file.txt to staging');
  

• Configuration: Store repo paths in .env:

  GIT_REPO_PATH=/var/www/repo
  

  $git = new Git(env('GIT_REPO_PATH'));
  

Gotchas and Tips

Pitfalls

1. Path Handling

   • Ensure paths are absolute and correctly formatted (e.g., /var/www/repo vs. ./repo).
   • Use realpath() to resolve relative paths:

     $git = new Git(realpath(__DIR__ . '/../repo'));
     

2. Permission Issues

   • Git operations may fail due to file permissions. Run:

     chmod -R 755 /path/to/repo
     

   • For SSH repos, ensure ~/.ssh has correct permissions (chmod 700 ~/.ssh).

3. Detached HEAD State

   • Operations like checkout or reset may leave the repo in a detached HEAD state. Reattach with:

     $git->branchCheckout('main');
     

4. Case Sensitivity

   • Branch/tag names are case-sensitive on Linux but not on Windows. Normalize names:

     $branch = strtolower('Feature/Login');
     $git->branchCreate($branch);
     

5. Large Files

   • Cloning repos with large files (e.g., binaries) may fail or timeout. Use --depth=1 for shallow clones:

     $git->clone('https://github.com/repo.git', ['--depth' => 1]);
     

Debugging

• Enable Verbose Output Pass Git’s -v flag via options:

  $git->pull(['-v']);
  

• Check Git Version Ensure the PHP wrapper matches your local Git version:

  $gitVersion = $git->version();
  Log::debug('Git version: ' . $gitVersion);
  

• Inspect Raw Commands Use Git::getLastCommand() to debug failed operations:

  try {
      $git->pull();
  } catch (\Exception $e) {
      Log::error('Failed command: ' . $git->getLastCommand());
  }
  

Extension Points

1. Custom Git Hooks Extend the package by adding pre/post hooks:

   $git->addEventListener('pre-commit', function() {
       // Run tests before commit
       exec('php artisan test');
   });
   

   (Note: Requires custom implementation; the package does not natively support hooks.)

2. Submodule Support For repos with submodules, manually initialize them:

   $git->submoduleUpdate(['--init', '--recursive']);
   

3. Custom Git Config Set global/local config via:

   $git->config('user.name', 'Your Name');
   $git->config('user.email', 'you@example.com');
   

4. Parallel Operations Use Laravel’s queues to run long Git operations asynchronously:

   GitOperation::dispatch($repoPath, 'pull')->onQueue('git');
   

   (Requires custom job class.)

Configuration Quirks

• SSH vs. HTTPS Prefer SSH for automation (avoids credential prompts):

  $git->clone('git@github.com:user/repo.git');
  

  For HTTPS, use a personal access token in the URL:

  $git->clone('https://user:token@github.com/user/repo.git');
  

• Line Endings Normalize line endings for cross-platform repos:

  $git->config('core.autocrlf', 'input'); // Preserve line endings