phacility/phabricator · warning · PhutilArgumentUsageException

Specify a revision to rebuild changesets for with "--revisio

Error message

Specify a revision to rebuild changesets for with "--revision".

What it means

PhabricatorDifferentialRebuildChangesetsWorkflow (./bin/differential rebuild-changesets) requires the --revision flag to know which revision's changesets to rebuild. Omitting it (or passing an empty value) throws this usage exception before any query runs, because rebuilding every revision is far too expensive to be an implicit default.

Source

Thrown at src/applications/differential/management/PhabricatorDifferentialRebuildChangesetsWorkflow.php:26

      ->setName('rebuild-changesets')
      ->setExamples('**rebuild-changesets** --revision __revision__')
      ->setSynopsis(pht('Rebuild changesets for a revision.'))
      ->setArguments(
        array(
          array(
            'name' => 'revision',
            'param' => 'revision',
            'help' => pht('Revision to rebuild changesets for.'),
          ),
        ));
  }

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

    $revision_identifier = $args->getArg('revision');
    if (!$revision_identifier) {
      throw new PhutilArgumentUsageException(
        pht('Specify a revision to rebuild changesets for with "--revision".'));
    }

    $revision = id(new PhabricatorObjectQuery())
      ->setViewer($viewer)
      ->withNames(array($revision_identifier))
      ->executeOne();
    if ($revision) {
      if (!($revision instanceof DifferentialRevision)) {
        throw new PhutilArgumentUsageException(
          pht(
            'Object "%s" specified by "--revision" must be a Differential '.
            'revision.',
            $revision_identifier));
      }
    } else {
      $revision = id(new DifferentialRevisionQuery())
        ->setViewer($viewer)

View on GitHub (pinned to 5720a38cfe)

Solutions

1. Re-run with the revision: ./bin/differential rebuild-changesets --revision D456
2. In scripts, guard with: test -n "$REV" && ./bin/differential rebuild-changesets --revision "$REV"
3. Fix the step that was supposed to supply the revision identifier

Example fix

# before
phabricator/ $ ./bin/differential rebuild-changesets
Usage Exception: Specify a revision to rebuild changesets for with "--revision".

# after
phabricator/ $ ./bin/differential rebuild-changesets --revision D456

# Require a revision before invoking
: "${REV:?--revision D<id> is required}"
phabricator/bin/differential rebuild-changesets --revision "$REV"

function isDifferentialMonogram($name) {
  return is_string($name) && preg_match('/^D\d+$/', $name);
}

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

When it happens

Trigger: Running './bin/differential rebuild-changesets' with no flags; a script passing --revision "$REV" with REV empty or unset; quoting that splits the value away from the flag.

Common situations: Post-migration maintenance (rebuilding changesets after hunk storage changes) where the operator forgets the one required flag; cron jobs with an unset revision variable.

Related errors

• Specify a hunk to migrate with "--id", or migrate all hunks
• Use "--to" to choose a storage format, or "--auto" to select
• Object "%s" specified by "--revision" must be a Differential
• Specify a commit and a revision to attach it to.
• Specify a commit to extract the diff from.

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