GitRemote::fetch(`HEAD`, ...) fails with `Branch "refs/heads/HEAD" not found`

[ivan-ottinger]

Summary

WordPress\Git\GitRemote::fetch() does not handle the symbolic ref HEAD. Called with 'HEAD', it synthesizes the literal name refs/heads/HEAD and asks the remote for it; no remote has such a ref, so it throws GitRemoteException: Branch "refs/heads/HEAD" not found on remote origin.

This blocks any Blueprint that uses git:directory with ref: "HEAD" when run through blueprints.phar. The JS Blueprints runtime accepts the same input, so the two runtimes diverge.

Reproduction

Save as blueprint.json:

{
  "$schema": "https://playground.wordpress.net/blueprint-schema.json",
  "steps": [
    {
      "step": "installPlugin",
      "options": { "activate": false, "targetFolderName": "wc-smooth-generator" },
      "pluginData": {
        "resource": "git:directory",
        "url": "https://github.com/woocommerce/wc-smooth-generator.git",
        "ref": "HEAD",
        "path": "/"
      }
    }
  ]
}

Run against any empty directory — create-new-site mode bootstraps WordPress + SQLite itself, no prior setup required:

SITE=$(mktemp -d)
php blueprints.phar exec ./blueprint.json \
  --mode=create-new-site \
  --site-path="$SITE" \
  --site-url=http://localhost:8881 \
  --db-engine=sqlite \
  --truncate-new-site-directory

The remote is reachable via standard git, ruling out a network/repo issue:

$ git ls-remote https://github.com/woocommerce/wc-smooth-generator.git HEAD
3f0cf484be9159fa5e3d1418768ae6cca400ab08	HEAD

Error

WordPress\Git\GitRemoteException: Branch "refs/heads/HEAD" not found on remote origin
  at components/Git/class-gitremote.php:100

#0 components/Git/class-gitremote.php(336): GitRemote->get_remote_head('refs/heads/HEAD')
#1 components/Git/class-gitremote.php(283): GitRemote->fetch('HEAD', Array)
#2 components/Blueprints/DataReference/class-datareferenceresolver.php(177): GitRemote->pull('HEAD', Array)

Code path

In components/Git/class-gitremote.php:

• fetch() builds 'refs/heads/' . $branch_name (line 336) and calls get_remote_head().
• get_remote_head() (line 100) calls ls_refs($full_branch_name) literally and throws if the exact key isn't returned.
• No method in the class resolves HEAD as a symref.

Environment

• blueprints.phar from Humbug Box 4.7.0.
• PHP 8.3.31.

[adamziel]

#294 landed, this should work now!

[ivan-ottinger]

#294 landed, this should work now!

Thank you for quickly addressing the issue, Adam!