phacility/phabricator · warning · PhutilArgumentUsageException

Use "--to" to choose a storage format, or "--auto" to select

Error message

Use "--to" to choose a storage format, or "--auto" to select a format automatically.

What it means

./bin/differential migrate-hunk requires a target format: either --to <type> (choose 'text' or 'file' explicitly) or --auto (let the tool select). With neither flag the workflow throws this usage exception, refusing to run a migration with an undefined destination format.

Source

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

          '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.'));
    }

    $types = array(
      DifferentialHunk::DATATYPE_TEXT,
      DifferentialHunk::DATATYPE_FILE,
    );
    $types = array_fuse($types);
    if (strlen($storage)) {
      if (!isset($types[$storage])) {
        throw new PhutilArgumentUsageException(
          pht(
            'Storage type "%s" is unknown. Supported types are: %s.',
            $storage,
            implode(', ', array_keys($types))));
      }

View on GitHub (pinned to 5720a38cfe)

Solutions

Add --auto for automatic selection ('./bin/differential migrate-hunk --all --auto') or --to text / --to file for an explicit format
Use --dry-run with the format choice to preview writes
In scripts, default the format flag to --auto when unset

Example fix

# before
phabricator/ $ ./bin/differential migrate-hunk --all
Usage Exception: Use "--to" to choose a storage format, or "--auto" ...

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

Defensive patterns

Strategy: validation

Validate before calling

# Default the format choice explicitly
FORMAT_FLAG="${FORMAT_FLAG:---auto}"   # or validate it is '--to text' / '--to file'
phabricator/bin/differential migrate-hunk --all $FORMAT_FLAG

Try / catch

try {
  $workflow->execute($args);
} catch (PhutilArgumentUsageException $ex) {
  // Missing format: append --auto (or --to text|file) and re-run.
}

Prevention

Never run migrate-hunk with scope flags only; the tool intentionally has no default format
Use --dry-run --auto to see what a complete, valid invocation would do

When it happens

Trigger: Running './bin/differential migrate-hunk --all' with scope but no format; scripts where the FORMAT variable is empty so '--to $FORMAT' is dropped; assuming a default format exists.

Common situations: First migrations following the scope-only part of a runbook; bash set -u absent so empty variables silently disappear; operators testing scope flags alone.

Related errors

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