Versioncontrol Hg Laravel Package

Getting Started

1. Install the package via Composer:

   composer require siad007/versioncontrol_hg
   

2. Ensure Mercurial is installed and available in your system’s PATH, as this package is a wrapper around the hg CLI binary.

3. Publish the config (if Laravel < 5.5) or auto-discover (5.5+):

   php artisan vendor:publish --provider="Siad007\VersionControlHg\VersionControlHgServiceProvider"
   

   This creates config/versioncontrol_hg.php.

4. First use case: Get status of a repository (PHP 8+ compatible):

   use Siad007\VersionControlHg\Repository;
   
   $repo = new Repository('/path/to/hg/repo');
   $status = $repo->status(); // Returns parsed output (added, modified, etc.)
   

Implementation Patterns

• Repository Abstraction: Instantiate Repository with a path to an existing Mercurial working copy. All hg commands map to methods:

  $log    = $repo->log(['limit' => 10]);      // hg log -l 10
  $branches = $repo->branches();               // hg branches
  $diff   = $repo->diff(['rev' => 'tip']);     // hg diff -r tip
  

• Programmatic commits with staged files:

  $repo->add(['src/new-file.php']);
  $repo->commit('Add new feature', ['user' => 'deployer <deploy@example.com>']);
  

• Laravel Integration: Bind Repository as a shared service using RepositoryFactory:

  // In a service provider or via injection
  $repo = app(Repository::class, ['path' => storage_path('app/hg-repo')]);
  

• Configuration via config: Set default paths, options (e.g., hg_path), or default user for commits in config/versioncontrol_hg.php.

• File-level operations: Stage, diff, or checkout specific files:

  $repo->revert('config/app.php'); // hg revert config/app.php
  

Gotchas and Tips

• No built-in repository creation: This package assumes the repo exists. Use hg init /path manually before using methods.

• Output parsing is CLI-dependent: Results depend on hg CLI output format; ensure the installed hg version matches expected format (last release was 2021 — may not support newer Mercurial features or flags).

• Working copy must be clean for certain actions: Commands like update() or revert() may fail if there are uncommitted conflicts; handle exceptions.

• Security consideration: Never pass untrusted input directly to command methods. Use parameterized options where possible; avoid string concatenation in command building.

• Error handling: Wrap calls in try/catch for RuntimeException (thrown on command failure). You can inspect $e->getMessage() or $e->getCode().

• PHP 8+ Compatibility: This package is now fully compatible with PHP 8+. No deprecation warnings or runtime issues should occur in PHP 8+ environments.

• Extensibility: Extend the Repository class to add custom commands not explicitly supported (e.g., hg graft, hg histedit) via runCommand():

  $result = $repo->runCommand('graft', ['--rev', $changeset]);
  

• Performance note: Each method call spawns a new hg process. For bulk operations (e.g., looped status() calls), batch where possible or consider spawning external scripts instead.