What causes "Specify a commit to extract the diff from." in phacility/phabricator?

Re-run with one commit identifier: ./bin/differential extract

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.

Solutions

Re-run with one commit identifier: ./bin/differential extract <commit>
Guard scripts: test -n "$COMMIT" && phabricator/./bin/differential extract "$COMMIT"
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

Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

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

Prevention

Fail fast in scripts when the commit variable is empty (set -u or :? expansion)
Pass exactly one fully qualified commit identifier per invocation

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

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

Appendix: 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)