phacility/phabricator · warning · PhutilArgumentUsageException

Specify a commit to extract the diff from.

Error message

Specify a commit to extract the diff from.

What it means

PhabricatorDifferentialExtractWorkflow (./bin/differential extract) requires at least one commit identifier in its 'extract' wildcard arguments. When none is supplied the workflow throws this usage exception immediately, before touching the database.

Source

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

      ->setExamples('**extract** __commit__')
      ->setSynopsis(pht('Extract a diff from a commit.'))
      ->setArguments(
        array(
          array(
            '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(

View on GitHub (pinned to 5720a38cfe)

Solutions

1. Re-run with one commit identifier: ./bin/differential extract <commit>
2. Guard scripts: test -n "$COMMIT" && phabricator/./bin/differential extract "$COMMIT"
3. Fix the upstream step that was supposed to populate the commit variable

Example fix

# before
phabricator/ $ ./bin/differential extract
Usage Exception: Specify a commit to extract the diff from.

# after
phabricator/ $ ./bin/differential extract rP703dcf56d0b6a4e01a52b1c6a1a1a8d1f8e2ab3c

# Guard against unset commit variables before invoking
: "${COMMIT:?COMMIT must be set to a commit identifier}"
phabricator/bin/differential extract "$COMMIT"

try {
  $workflow->execute($args);
} catch (PhutilArgumentUsageException $ex) {
  // Missing argument: populate it and re-run; nothing was modified.
}

When it happens

Trigger: Running './bin/differential extract' with no arguments; an empty shell variable expanding to nothing ($COMMIT unset); a script passing an empty array of commits.

Common situations: Deploy scripts referencing an unset environment variable; CI jobs where the commit-ref step failed silently and passed an empty value.

Related errors

• Specify exactly one commit to extract.
• Specify a commit and a revision to attach it to.
• Commit "%s" is not valid.
• Options "--all" (to migrate all hunks) and "--id" (to migrat
• Specify a hunk to migrate with "--id", or migrate all hunks

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