Getting Started

Minimal Setup

Installation: Require the package via Composer:
```
composer require --dev sweetchuck/robo-git
```

Usage: Add the GitTaskLoader trait to your RoboFile.php:

use Sweetchuck\Robo\Git\GitTaskLoader;

class RoboFile extends \Robo\Tasks
{
    use GitTaskLoader;
}

First Use Case: List branches in the current directory:

public function gitBranches()
{
    return $this->taskGitBranchList()->run();
}

Run with:

vendor/bin/robo git:branches

Implementation Patterns

Common Workflows

Data-Driven Pipelines: Use State\Data to chain tasks. Example: Fetch branch info, then filter branches:

public function filterBranches()
{
    return $this->collectionBuilder()
        ->addTask($this->taskGitBranchList())
        ->addCode(function (\Robo\State\Data $data) {
            $branches = array_filter($data['gitBranches'], function ($branch) {
                return strpos($branch['refName.short'], 'feature/') === 0;
            });
            $this->output()->writeln('Filtered branches: ' . implode(', ', array_keys($branches)));
        });
}

Conditional Logic: Use parsed Git data to drive workflows. Example: Check if a branch exists:

public function checkBranchExists(string $branchName)
{
    return $this->collectionBuilder()
        ->addTask($this->taskGitBranchList())
        ->addCode(function (\Robo\State\Data $data) use ($branchName) {
            $exists = isset($data['gitBranches'][$branchName]);
            $this->output()->writeln($branchName . ' exists: ' . ($exists ? 'Yes' : 'No'));
            return $exists ? 0 : 1;
        });
}

Directory-Specific Operations: Set workingDirectory for repo-agnostic tasks:

public function listFilesInRepo(string $repoPath)
{
    return $this->taskGitListFiles()
        ->setPaths(['*.php'])
        ->setWorkingDirectory($repoPath);
}

Configuration Integration: Fetch Git config dynamically:

public function getGitConfig(string $key)
{
    return $this->taskGitConfigGet()->setName($key);
}

Integration Tips

Laravel Artisan: Extend Laravel’s Artisan with custom Git tasks:

// app/Console/Kernel.php
protected $commands = [
    \App\Console\Commands\GitBranchCommand::class,
];

CI/CD Pipelines: Use parsed Git data (e.g., gitCurrentBranch) to trigger workflows:

public function deployIfMainBranch()
{
    return $this->collectionBuilder()
        ->addTask($this->taskGitCurrentBranch())
        ->addCode(function (\Robo\State\Data $data) {
            if ($data['gitCurrentBranch.short'] === 'main') {
                $this->taskExec('php artisan deploy')->run();
            }
        });
}

Gotchas and Tips

Pitfalls

Data Key Confusion:
- taskGitBranchList() stores results in $data['gitBranches'], not $data['branches'].
- taskGitListFiles() uses $data['files'] with ListFilesItem objects (not plain arrays).
Working Directory:
- Forgetting setWorkingDirectory() defaults to the current directory, which may not be the repo root. Always specify explicitly for clarity:
```
->setWorkingDirectory(base_path('../'))
```

Error Handling:

Git commands may fail silently. Validate $data keys before use:

if (!isset($data['gitCurrentBranch'])) {
    $this->output()->writeln('Git operation failed!');
    return 1;
}

Undocumented Options:
- Some tasks (e.g., taskGitListFiles) support Git’s full option set, but not all are documented in the README. Refer to git --help for advanced flags.

Debugging

Inspect Raw Output: Use taskExec() alongside robo-git tasks to debug raw Git output:
```
$this->taskExec('git branch --all')->run();
```

State Data Dumping: Dump the entire $data object to inspect available keys:

->addCode(function (\Robo\State\Data $data) {
    $this->output()->writeln(print_r($data->getAll(), true));
})

Tips

Extend for Custom Logic: Override task methods to add custom parsing. Example: Extract commit hashes from git log:

use Sweetchuck\Robo\Git\GitTaskLoader;

class CustomRoboFile extends \Robo\Tasks
{
    use GitTaskLoader;

    public function taskGitLog()
    {
        return $this->taskExec('git log --pretty=format:"%H"')
            ->setOutputBuffering(true);
    }
}

Performance: Cache frequent operations (e.g., branch lists) in State\Data:

->addCode(function (\Robo\State\Data $data) {
    if (!$data->has('cachedBranches')) {
        $data->set('cachedBranches', $this->taskGitBranchList()->run());
    }
})

Type Safety: Use PHP 8’s array_key_exists() or isset() with strict checks for ListFilesItem objects:

foreach ($data['files'] as $file) {
    if ($file instanceof \Sweetchuck\Robo\Git\ListFilesItem) {
        $this->output()->writeln($file->fileName);
    }
}

Configuration: Store repetitive Git configs (e.g., user.email) in robo.yml:
```
git:
  user:
    email: "dev@example.com"
```
Then fetch dynamically:
```
$this->taskGitConfigGet()->setName('user.email');
```
Testing: Mock Git commands in tests using taskExec() with fixed outputs:
```
$this->taskExec('git branch')->expects($this->once())->run();
```


```markdown
## Extension Points
1. **Custom Tasks**:
   Extend the package by creating wrapper tasks for unsupported Git commands. Example:
   ```php
   public function taskGitDiffStats()
   {
       return $this->taskExec('git diff --stat')
           ->setOutputBuffering(true);
   }

Data Parsers: Override the default output parsers (e.g., for taskGitBranchList) to customize data structure:

public function taskGitBranchList()
{
    $task = parent::taskGitBranchList();
    $task->setParser(function ($output) {
        // Custom parsing logic
        return ['custom' => 'data'];
    });
    return $task;
}

Integration with Laravel: Bind Robo tasks to Laravel’s service container for dependency injection:

$this->app->bind(\Sweetchuck\Robo\Git\GitTaskLoader::class, function () {
    return new class extends \Sweetchuck\Robo\Git\GitTaskLoader {
        // Custom logic
    };
});

Event Listeners: Attach listeners to task execution for logging/auditing:

$this->taskGitBranchList()->addListener(function ($task) {
    $this->output()->writeln('Branch list task started');
});

Robo Git Laravel Package