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.

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.

Understand the failure class

Background: "Must pass :limit option" / "Missing required option" — required option errors explained — this error's family across 41 libraries.

Related errors

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

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