phacility/phabricator · warning · PhutilArgumentUsageException

Options "--to" (to choose a specific storage format) and "--

Error message

Options "--to" (to choose a specific storage format) and "--auto" (to select a storage format automatically) are mutually exclusive.

What it means

./bin/differential migrate-hunk lets you pick the target storage format either explicitly with --to <type> or automatically with --auto. Passing both is contradictory (auto-selection versus explicit choice), so the workflow throws this usage exception before validating the type value.

Source

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

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

    $types = array(
      DifferentialHunk::DATATYPE_TEXT,
      DifferentialHunk::DATATYPE_FILE,
    );
    $types = array_fuse($types);
    if (strlen($storage)) {
      if (!isset($types[$storage])) {

View on GitHub (pinned to 5720a38cfe)

Solutions

Choose one: --to text|file for an explicit format, or --auto to let Phabricator pick
Parametrize the format flags in scripts so exactly one of --to/--auto is emitted
Follow with --dry-run to verify the selected behavior before the real run

Example fix

# before
phabricator/ $ ./bin/differential migrate-hunk --all --to text --auto
Usage Exception: Options "--to" ... and "--auto" ... are mutually exclusive.

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

Defensive patterns

Strategy: validation

Validate before calling

# Emit exactly one format flag
if [ -n "$TO_FORMAT" ] && [ "$AUTO" = "1" ]; then
  echo "pick either --to or --auto, not both" >&2; exit 64
fi
phabricator/bin/differential migrate-hunk --all ${TO_FORMAT:+--to "$TO_FORMAT"} ${AUTO:+--auto}

Try / catch

try {
  $workflow->execute($args);
} catch (PhutilArgumentUsageException $ex) {
  // --to/--auto conflict: keep one flag, re-run.
}

Prevention

Represent the format choice as one tri-state variable (auto|text|file) in wrappers
Prefer --auto in scheduled migrations; reserve --to for deliberate, tested migrations

When it happens

Trigger: Running './bin/differential migrate-hunk --all --to text --auto'; scripts templating '--to $FORMAT' while also hardcoding --auto; combining flags from two different documented invocations.

Common situations: Runbook evolution where --auto was added later to an existing command with --to; cron wrappers appending flags conditionally until both appear.

Related errors

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