{"record":{"id":"ed85e1cb98942938","repo":"phacility/phabricator","slug":"specify-a-hunk-to-migrate-with-id-or-migrate","errorCode":null,"errorMessage":"Specify a hunk to migrate with \"--id\", or migrate all hunks with \"--all\".","messagePattern":"Specify a hunk to migrate with \"--id\", or migrate all hunks with \"--all\"\\.","errorType":"console","errorClass":"PhutilArgumentUsageException","httpStatus":null,"severity":"warning","filePath":"src/applications/differential/management/PhabricatorDifferentialMigrateHunkWorkflow.php","lineNumber":52,"sourceCode":"            'name' => 'dry-run',\n            'help' => pht('Show planned writes but do not perform them.'),\n          ),\n        ));\n  }\n\n  public function execute(PhutilArgumentParser $args) {\n    $is_dry_run = $args->getArg('dry-run');\n\n    $id = $args->getArg('id');\n    $is_all = $args->getArg('all');\n\n    if ($is_all && $id) {\n      throw new PhutilArgumentUsageException(\n        pht(\n          'Options \"--all\" (to migrate all hunks) and \"--id\" (to migrate a '.\n          'specific hunk) are mutually exclusive.'));\n    } else if (!$is_all && !$id) {\n      throw new PhutilArgumentUsageException(\n        pht(\n          'Specify a hunk to migrate with \"--id\", or migrate all hunks '.\n          'with \"--all\".'));\n    }\n\n    $is_auto = $args->getArg('auto');\n    $storage = $args->getArg('to');\n    if ($is_auto && $storage) {\n      throw new PhutilArgumentUsageException(\n        pht(\n          'Options \"--to\" (to choose a specific storage format) and \"--auto\" '.\n          '(to select a storage format automatically) are mutually '.\n          'exclusive.'));\n    } else if (!$is_auto && !$storage) {\n      throw new PhutilArgumentUsageException(\n        pht(\n          'Use \"--to\" to choose a storage format, or \"--auto\" to select a '.\n          'format automatically.'));","sourceCodeStart":34,"sourceCodeEnd":70,"githubUrl":"https://github.com/phacility/phabricator/blob/5720a38cfe95b00ca4be5016dd0d2f3195f4fa04/src/applications/differential/management/PhabricatorDifferentialMigrateHunkWorkflow.php#L34-L70","documentation":"./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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"# before\nphabricator/ $ ./bin/differential migrate-hunk --auto\nUsage Exception: Specify a hunk to migrate with \"--id\", or migrate all hunks with \"--all\".\n\n# after\nphabricator/ $ ./bin/differential migrate-hunk --all --auto","handlingStrategy":"validation","validationCode":"# Require exactly one scope before invoking\nif [ -z \"$HUNK_ID\" ] && [ \"$ALL\" != \"1\" ]; then\n  echo \"specify --id <id> or --all\" >&2; exit 64\nfi","typeGuard":null,"tryCatchPattern":"try {\n  $workflow->execute($args);\n} catch (PhutilArgumentUsageException $ex) {\n  // Missing scope: choose --all or --id and re-run; no writes occurred.\n}","preventionTips":["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"],"tags":["phabricator","differential","cli","migrate-hunk","missing-option","usage-error"],"backgroundTag":"missing-required-option","analyzedSha":"5720a38cfe95b00ca4be5016dd0d2f3195f4fa04","analyzedAt":"2026-08-21T05:07:25.672Z","schemaVersion":2},"datasetVersion":"2026-08-21T11:28:35.574Z"}