diff --git a/src/toolset/ArcanistWorkflowArgument.php b/src/toolset/ArcanistWorkflowArgument.php --- a/src/toolset/ArcanistWorkflowArgument.php +++ b/src/toolset/ArcanistWorkflowArgument.php @@ -10,6 +10,7 @@ private $isPathArgument; private $shortFlag; private $repeatable; + private $relatedConfig = array(); public function setKey($key) { $this->key = $key; @@ -47,6 +48,15 @@ return $this->repeatable; } + public function addRelatedConfig($related_config) { + $this->relatedConfig[] = $related_config; + return $this; + } + + public function getRelatedConfig() { + return $this->relatedConfig; + } + public function getPhutilSpecification() { $spec = array( 'name' => $this->getKey(), @@ -63,6 +73,20 @@ $help = $this->getHelp(); if ($help !== null) { + $config = $this->getRelatedConfig(); + + if ($config) { + $more = array(); + foreach ($this->getRelatedConfig() as $config) { + $more[] = tsprintf( + '%s **%s**', + pht('Related configuration:'), + $config); + } + $more = phutil_glue($more, "\n"); + $help = tsprintf("%B\n\n%B", $help, $more); + } + $spec['help'] = $help; } @@ -80,6 +104,10 @@ } public function setHelp($help) { + if (is_array($help)) { + $help = implode("\n\n", $help); + } + $this->help = $help; return $this; } diff --git a/src/workflow/ArcanistLandWorkflow.php b/src/workflow/ArcanistLandWorkflow.php --- a/src/workflow/ArcanistLandWorkflow.php +++ b/src/workflow/ArcanistLandWorkflow.php @@ -12,82 +12,111 @@ public function getWorkflowInformation() { $help = pht(<<newWorkflowArgument('hold') ->setHelp( pht( - 'Prepare the change to be pushed, but do not actually push it.')), + 'Prepare the changes to be pushed, but do not actually push '. + 'them.')), $this->newWorkflowArgument('keep-branches') ->setHelp( pht( 'Keep local branches around after changes are pushed. By '. - 'default, local branches are deleted after they land.')), + 'default, local branches are deleted after the changes they '. + 'contain are published.')), $this->newWorkflowArgument('onto-remote') ->setParameter('remote-name') - ->setHelp(pht('Push to a remote other than the default.')), - - // TODO: Formally allow flags to be bound to related configuration - // for documentation, e.g. "setRelatedConfiguration('arc.land.onto')". - + ->setHelp(pht('Push to a remote other than the default.')) + ->addRelatedConfig('arc.land.onto-remote'), $this->newWorkflowArgument('onto') ->setParameter('branch-name') ->setRepeatable(true) + ->addRelatedConfig('arc.land.onto') ->setHelp( - pht( - 'After merging, push changes onto a specified branch. '. - 'Specifying this flag multiple times will push multiple '. - 'branches.')), + array( + pht( + 'After merging, push changes onto a specified branch.'), + pht( + 'Specifying this flag multiple times will push to multiple '. + 'branches.'), + )), $this->newWorkflowArgument('strategy') ->setParameter('strategy-name') + ->addRelatedConfig('arc.land.strategy') ->setHelp( - pht( - // TODO: Improve this. - 'Merge using a particular strategy.')), + array( + pht( + 'Merge using a particular strategy. Supported strategies are '. + '"squash" and "merge".'), + pht( + 'The "squash" strategy collapses multiple local commits into '. + 'a single commit when publishing. It produces a linear '. + 'published history (but discards local checkpoint commits). '. + 'This is the default strategy.'), + pht( + 'The "merge" strategy generates a merge commit when publishing '. + 'that retains local checkpoint commits (but produces a '. + 'nonlinear published history). Select this strategy if you do '. + 'not want "arc land" to discard checkpoint commits.'), + )), $this->newWorkflowArgument('revision') ->setParameter('revision-identifier') ->setHelp( pht( - 'Land a specific revision, rather than determining the revisions '. - 'from the commits that are landing.')), + 'Land a specific revision, rather than determining revisions '. + 'automatically from the commits that are landing.')), $this->newWorkflowArgument('preview') ->setHelp( pht( - 'Shows the changes that will land. Does not modify the working '. + 'Show the changes that will land. Does not modify the working '. 'copy or the remote.')), $this->newWorkflowArgument('into') ->setParameter('commit-ref') ->setHelp( pht( - 'Specifies the state to merge into. By default, this is the same '. + 'Specify the state to merge into. By default, this is the same '. 'as the "onto" ref.')), $this->newWorkflowArgument('into-remote') ->setParameter('remote-name') @@ -166,13 +211,17 @@ '"into" state is not specified.')), $this->newWorkflowArgument('incremental') ->setHelp( - pht( - 'When landing multiple revisions at once, push and rebase '. - 'after each operation instead of waiting until all merges '. - 'are completed. This is slower than the default behavior and '. - 'not atomic, but may make it easier to resolve conflicts and '. - 'land complicated changes by letting you make progress one '. - 'step at a time.')), + array( + pht( + 'When landing multiple revisions at once, push and rebase '. + 'after each merge completes instead of waiting until all '. + 'merges are completed to push.'), + pht( + 'This is slower than the default behavior and not atomic, '. + 'but may make it easier to resolve conflicts and land '. + 'complicated changes by allowing you to make progress one '. + 'step at a time.'), + )), $this->newWorkflowArgument('ref') ->setWildcard(true), );