What causes "Specify exactly one commit to extract." in phacility/phabricator?

Run one extraction per commit, or wrap in a loop: for c in $commits; do ./bin/differential extract "$c"; done

phacility/phabricator · warning · PhutilArgumentUsageException

Specify exactly one commit to extract.

Error message

Specify exactly one commit to extract.

What it means

./bin/differential extract accepts exactly one commit to convert into a Differential diff; if the wildcard 'extract' argument contains more than one identifier, the workflow throws this usage exception. The limit exists because each extraction creates a diff and echoes its URI, which is only meaningful for a single commit.

Source

Thrown at src/applications/differential/management/PhabricatorDifferentialExtractWorkflow.php:32

            'name' => 'extract',
            'wildcard' => true,
            'help' => pht('Commit to extract.'),
          ),
        ));
  }

  public function execute(PhutilArgumentParser $args) {
    $viewer = $this->getViewer();

    $extract = $args->getArg('extract');

    if (!$extract) {
      throw new PhutilArgumentUsageException(
        pht('Specify a commit to extract the diff from.'));
    }

    if (count($extract) > 1) {
      throw new PhutilArgumentUsageException(
        pht('Specify exactly one commit to extract.'));
    }

    $extract = head($extract);

    $commit = id(new DiffusionCommitQuery())
      ->setViewer($viewer)
      ->withIdentifiers(array($extract))
      ->executeOne();

    if (!$commit) {
      throw new PhutilArgumentUsageException(
        pht(
          'Commit "%s" is not valid.',
          $extract));
    }

    $diff = id(new DifferentialDiffExtractionEngine())

View on GitHub (pinned to 5720a38cfe)

Solutions

Run one extraction per commit, or wrap in a loop: for c in $commits; do ./bin/differential extract "$c"; done
Quote the identifier and ensure the variable holds exactly one ref
If you need diffs for many commits, script repeated single extractions

Example fix

# before
phabricator/ $ ./bin/differential extract rPabc1234 rPdef5678
Usage Exception: Specify exactly one commit to extract.

# after
phabricator/ $ ./bin/differential extract rPabc1234 && \
  phabricator/ $ ./bin/differential extract rPdef5678

Defensive patterns

Strategy: validation

Validate before calling

// If iterating commits, enforce one per invocation:
foreach ($commits as $commit) {
  // invoke './bin/differential extract <commit>' once per element
}

Type guard

function isSingleIdentifier(array $argv) {
  return count($argv) === 1;
}

Try / catch

try {
  $workflow->execute($args);
} catch (PhutilArgumentUsageException $ex) {
  // Too many commits: split the argument list and run one extraction each.
}

Prevention

Quote single refs and avoid unquoted glob expansion (tags/*) on the command line
Wrap batch needs in a shell loop rather than passing many identifiers at once

When it happens

Trigger: Passing several commits ('./bin/differential extract a b c'); an unquoted glob that expands to multiple refs (e.g., ./bin/differential extract tags/*); a loop bug that accumulates identifiers into one command line.

Common situations: Shell scripts using $@ unquoted where one ref expands to many; users trying to batch-extract; CI passing a ref list instead of one SHA.

Related errors

AI-assisted analysis of phacility/phabricator@5720a38cfe (2026-08-21). Data as JSON: /api/errors/991cdf057eaccdc0. Report an issue: GitHub.