Gitelephant Laravel Package

Getting Started

First Steps

1. Installation

   composer require cypresslab/gitelephant
   

   Add the service provider to config/app.php:

   'providers' => [
       // ...
       CypressLab\GitElephant\GitElephantServiceProvider::class,
   ],
   

2. Basic Usage Initialize GitElephant in a controller, command, or service:

   use CypressLab\GitElephant\GitElephant;
   
   $git = app(GitElephant::class);
   $git->setRepository('/path/to/repo');
   

3. First Use Case: Clone a Repository

   $git->clone('https://github.com/user/repo.git', '/local/path');
   

Implementation Patterns

Core Workflows

1. Repository Operations

   • Initialize a repo:

     $git->init('/path/to/repo');
     

   • Check status:

     $status = $git->status(); // Returns array of staged/unstaged files
     

   • Commit changes:

     $git->add(['file1.txt', 'file2.php']);
     $git->commit('Update README');
     

2. Branching & Merging

   • Create/Checkout branch:

     $git->checkout('feature-branch');
     $git->createBranch('feature-branch');
     

   • Merge branches:

     $git->merge('main');
     

3. Remote Operations

   • Add/Remove remotes:

     $git->addRemote('origin', 'https://github.com/user/repo.git');
     $git->removeRemote('origin');
     

   • Fetch/Pull/Push:

     $git->fetch('origin');
     $git->pull('origin', 'main');
     $git->push('origin', 'feature-branch');
     

4. Tagging & Releases

   • Create/Delete tags:

     $git->tag('v1.0.0', 'Release 1.0');
     $git->deleteTag('v1.0.0');
     

Integration Tips

• Laravel Artisan Commands Use GitElephant in custom commands for deployments or CI/CD hooks:

  use CypressLab\GitElephant\GitElephant;
  
  class DeployCommand extends Command {
      protected $git;
  
      public function __construct(GitElephant $git) {
          parent::__construct();
          $this->git = $git;
      }
  
      public function handle() {
          $this->git->pull('origin', 'main');
          // Run deployment logic...
      }
  }
  

• Event Listeners Trigger actions on Git events (e.g., post-commit hooks):

  use CypressLab\GitElephant\Events\GitEvent;
  
  public function handle(GitEvent $event) {
      if ($event->action === 'commit') {
          // Notify team or update database
      }
  }
  

• Queue Jobs Offload long-running Git operations (e.g., large clones) to queues:

  CloneRepo::dispatch('https://github.com/user/repo.git', '/storage/repos')->onQueue('git');
  

Gotchas and Tips

Common Pitfalls

1. Repository Path Handling

   • Ensure paths are absolute and writable. Relative paths may fail silently.
   • Example:

     $git->setRepository(__DIR__ . '/../../repo'); // Use absolute paths
     

2. Git Binary Dependencies

   • GitElephant relies on the system’s git binary. Verify it’s installed and in $PATH.
   • Debug missing binary:

     which git  # Should return /usr/bin/git or similar
     

3. Permission Issues

   • Clone/pull/push operations may fail due to SSH keys or HTTPS credentials.
   • For SSH: Ensure ~/.ssh/id_rsa is configured and added to ssh-agent.
   • For HTTPS: Use git config --global credential.helper store to cache credentials.

4. Detached HEAD States

   • Operations like checkout('commit-hash') may leave the repo in a detached HEAD state.
   • Reattach with:

     $git->checkout('main'); // Return to a branch
     

5. Large Repositories

   • Cloning/pushing large repos (e.g., >1GB) may time out or fail.
   • Mitigate with:

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

Debugging Tips

• Enable Verbose Output Pass --verbose to Git commands:

  $git->setVerbose(true); // Logs raw Git output
  

• Check Return Codes GitElephant returns false on failure. Inspect $git->getLastError():

  if (!$git->pull('origin', 'main')) {
      $this->error($git->getLastError());
  }
  

• Log Git Commands Override GitElephant to log executed commands:

  $git->setLogger(function ($command) {
      \Log::debug("Executed: {$command}");
  });
  

Extension Points

1. Custom Git Commands Extend GitElephant to support custom Git commands:

   $git->execute('git submodule update --init');
   

2. Hooks & Events Subscribe to Git events (e.g., pre-commit, post-merge):

   $git->on('pre-commit', function () {
       // Run linters, tests, etc.
   });
   

3. Repository Factories Create reusable repo configurations:

   $repo = new \CypressLab\GitElephant\Repository('/path/to/repo');
   $repo->setRemote('origin', 'https://github.com/user/repo.git');
   $git->useRepository($repo);
   

4. SSH Key Management For automated deployments, configure SSH keys programmatically:

   $git->setSshKey('/path/to/private_key');
   $git->setSshPassphrase('your_passphrase');
   

Configuration Quirks

• Git Config Overrides Override global Git settings per repository:

  $git->config('user.name', 'GitElephant');
  $git->config('user.email', 'git@elephant.com');
  

• Case Sensitivity Branch/tag names are case-sensitive on some systems (e.g., Linux). Normalize case if needed:

  $branch = strtolower($git->getCurrentBranch());