phacility/phabricator · warning · PhutilArgumentUsageException

Specify a hunk to migrate with "--id", or migrate all hunks

Error message

Specify a hunk to migrate with "--id", or migrate all hunks with "--all".

What it means

./bin/differential migrate-hunk requires an explicit scope: either --id <id> for one hunk or --all for all hunks. When neither is given, the workflow throws this usage exception immediately, because migrating nothing is never intended and the tool refuses to guess.

Source

Thrown at src/applications/differential/management/PhabricatorDifferentialMigrateHunkWorkflow.php:52

            'name' => 'dry-run',
            'help' => pht('Show planned writes but do not perform them.'),
          ),
        ));
  }

  public function execute(PhutilArgumentParser $args) {
    $is_dry_run = $args->getArg('dry-run');

    $id = $args->getArg('id');
    $is_all = $args->getArg('all');

    if ($is_all && $id) {
      throw new PhutilArgumentUsageException(
        pht(
          'Options "--all" (to migrate all hunks) and "--id" (to migrate a '.
          'specific hunk) are mutually exclusive.'));
    } else if (!$is_all && !$id) {
      throw new PhutilArgumentUsageException(
        pht(
          'Specify a hunk to migrate with "--id", or migrate all hunks '.
          'with "--all".'));
    }

    $is_auto = $args->getArg('auto');
    $storage = $args->getArg('to');
    if ($is_auto && $storage) {
      throw new PhutilArgumentUsageException(
        pht(
          'Options "--to" (to choose a specific storage format) and "--auto" '.
          '(to select a storage format automatically) are mutually '.
          'exclusive.'));
    } else if (!$is_auto && !$storage) {
      throw new PhutilArgumentUsageException(
        pht(
          'Use "--to" to choose a storage format, or "--auto" to select a '.
          'format automatically.'));

View on GitHub (pinned to 5720a38cfe)

Solutions

Add --all to migrate every hunk, or --id <id> for a specific one
Pair --dry-run with the chosen scope for a safe first run: './bin/differential migrate-hunk --all --auto --dry-run'
In scripts, fail early if neither scope variable is set

Example fix

# before
phabricator/ $ ./bin/differential migrate-hunk --auto
Usage Exception: Specify a hunk to migrate with "--id", or migrate all hunks with "--all".

# after
phabricator/ $ ./bin/differential migrate-hunk --all --auto

Defensive patterns

Strategy: validation

Validate before calling

# Require exactly one scope before invoking
if [ -z "$HUNK_ID" ] && [ "$ALL" != "1" ]; then
  echo "specify --id <id> or --all" >&2; exit 64
fi

Try / catch

try {
  $workflow->execute($args);
} catch (PhutilArgumentUsageException $ex) {
  // Missing scope: choose --all or --id and re-run; no writes occurred.
}

Prevention

Default the scope explicitly in runbooks (--all for bulk, --id for targeted testing)
Treat migrate-hunk as unsafe to run without both a scope and a format decision

When it happens

Trigger: Running migrate-hunk with only target-format flags (e.g., './bin/differential migrate-hunk --auto' or '--to text') and forgetting the scope; scripts whose scope variable is empty; operators assuming --auto implies --all.

Common situations: First-time use of the hunk migration tool; runbooks that document the --to/--auto flags more prominently than the scope flags; bash scripts with unset variables expanding to no flag.

Related errors

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