Page MenuHomePhabricator

abstract class ArcanistWorkflow
Arcanist Technical Documentation (Workflows)

Implements a runnable command, like "arc diff" or "arc help".

Managing Conduit

Workflows have the builtin ability to open a Conduit connection to a Phabricator installation, so methods can be invoked over the API. Workflows may either not need this (e.g., "help"), or may need a Conduit but not authentication (e.g., calling only public APIs), or may need a Conduit and authentication (e.g., "arc diff").

To specify that you need an unauthenticated conduit, override requiresConduit() to return true. To specify that you need an authenticated conduit, override requiresAuthentication() to return true. You can also manually invoke establishConduit() and/or authenticateConduit() later in a workflow to upgrade it. Once a conduit is open, you can access the client by calling getConduit(), which allows you to invoke methods. You can get verified information about the user identity by calling getUserPHID() or getUserName() after authentication occurs.

Scratch Files

Arcanist workflows can read and write 'scratch files', which are temporary files stored in the project that persist across commands. They can be useful if you want to save some state, or keep a copy of a long message the user entered if something goes wrong.

Tasks

Conduit

  • final public function setConduitURI($conduit_uri) — Set the URI which the workflow will open a conduit connection to when @{method:establishConduit} is called. Arcanist makes an effort to set this by default for all workflows (by reading ##.arcconfig## and/or the value of ##--conduit-uri##) even if they don't need Conduit, so a workflow can generally upgrade into a conduit workflow later by just calling @{method:establishConduit}.
  • final public function getConduitURI() — Returns the URI the conduit connection within the workflow uses.
  • final public function establishConduit() — Open a conduit channel to the server which was previously configured by calling @{method:setConduitURI}. Arcanist will do this automatically if the workflow returns ##true## from @{method:requiresConduit}, or you can later upgrade a workflow and build a conduit by invoking it manually.
  • final public function setConduitCredentials($credentials) — Set credentials which will be used to authenticate against Conduit. These credentials can then be used to establish an authenticated connection to conduit by calling @{method:authenticateConduit}. Arcanist sets some defaults for all workflows regardless of whether or not they return true from @{method:requireAuthentication}, based on the ##~/.arcrc## and ##.arcconf## files if they are present. Thus, you can generally upgrade a workflow which does not require authentication into an authenticated workflow by later invoking @{method:requireAuthentication}. You should not normally need to call this method unless you are specifically overriding the defaults.
  • final public function forceConduitVersion($version) — Force arc to identify with a specific Conduit version during the protocol handshake. This is primarily useful for development (especially for sending diffs which bump the client Conduit version), since the client still actually speaks the builtin version of the protocol.
  • final public function getConduitVersion() — Get the protocol version the client should identify with.
  • final public function setConduitTimeout($timeout) — Override the default timeout for Conduit.
  • final public function authenticateConduit() — Open and authenticate a conduit connection to a Phabricator server using provided credentials. Normally, Arcanist does this for you automatically when you return true from @{method:requiresAuthentication}, but you can also upgrade an existing workflow to one with an authenticated conduit by invoking this method manually.
  • final protected function isConduitAuthenticated()
  • public function requiresConduit() — Override this to return true if your workflow requires a conduit channel. Arc will build the channel for you before your workflow executes. This implies that you only need an unauthenticated channel; if you need authentication, override @{method:requiresAuthentication}.
  • public function requiresAuthentication() — Override this to return true if your workflow requires an authenticated conduit channel. This implies that it requires a conduit. Arc will build and authenticate the channel for you before the workflow executes.
  • final public function getUserPHID() — Returns the PHID for the user once they've authenticated via Conduit.
  • final public function getUserName() — Return the username for the user once they've authenticated via Conduit.
  • final public function getConduit() — Get the established @{class@libphutil:ConduitClient} in order to make Conduit method calls. Before the client is available it must be connected, either implicitly by making @{method:requireConduit} or @{method:requireAuthentication} return true, or explicitly by calling @{method:establishConduit} or @{method:authenticateConduit}.

Scratch Files

  • final protected function readScratchFile($path) — Try to read a scratch file, if it exists and is readable.
  • final protected function readScratchJSONFile($path) — Try to read a scratch JSON file, if it exists and is readable.
  • final protected function writeScratchFile($path, $data) — Try to write a scratch file, if there's somewhere to put it and we can write there.
  • final protected function writeScratchJSONFile($path, $data) — Try to write a scratch JSON file, if there's somewhere to put it and we can write there.
  • final protected function removeScratchFile($path) — Try to remove a scratch file.
  • final protected function getReadableScratchFilePath($path) — Get a human-readable description of the scratch file location.
  • final protected function getScratchFilePath($path) — Get the path to a scratch file, if possible.

Phabricator Repositories

  • final protected function getRepositoryPHID() — Get the PHID of the Phabricator repository this working copy corresponds to. Returns `null` if no repository can be identified.
  • final protected function getRepositoryName() — Get the name of the Phabricator repository this working copy corresponds to. Returns `null` if no repository can be identified.
  • final protected function getRepositoryURI() — Get the URI of the Phabricator repository this working copy corresponds to. Returns `null` if no repository can be identified.
  • final protected function getRepositoryReasons() — Get human-readable reasoning explaining how `arc` evaluated which Phabricator repository corresponds to this working copy. Used by `arc which` to explain the process to users.
  • private function getRepositoryInformation()
  • private function loadRepositoryInformation()
  • private function getRepositoryQuery()

Other Methods

Methods

public function __get($name)
Inherited

This method is not documented.
Parameters
$name
Return
wild

public function __set($name, $value)
Inherited

This method is not documented.
Parameters
$name
$value
Return
wild

public function current()
Inherited

This method is not documented.
Return
wild

public function key()
Inherited

This method is not documented.
Return
wild

public function next()
Inherited

This method is not documented.
Return
wild

public function rewind()
Inherited

This method is not documented.
Return
wild

public function valid()
Inherited

This method is not documented.
Return
wild

private function throwOnAttemptedIteration()
Inherited

This method is not documented.
Return
wild

public function getPhobjectClassConstant($key, $byte_limit)
Inherited

Phobject

Read the value of a class constant.

This is the same as just typing self::CONSTANTNAME, but throws a more useful message if the constant is not defined and allows the constant to be limited to a maximum length.

Parameters
string$keyName of the constant.
int|null$byte_limitMaximum number of bytes permitted in the value.
Return
stringValue of the constant.

public function __construct()

This method is not documented.
Return
this//Implicit.//

abstract public function run()

This method is not documented.
Return
wild

public function finalize()

Finalizes any cleanup operations that need to occur regardless of whether the command succeeded or failed.

Return
wild

abstract public function getWorkflowName()

Return the command used to invoke this workflow from the command like, e.g. "help" for ArcanistHelpWorkflow.

Return
stringThe command a user types to invoke this workflow.

abstract public function getCommandSynopses()

Return console formatted string with all command synopses.

Return
string6-space indented list of available command synopses.

abstract public function getCommandHelp()

Return console formatted string with command help printed in arc help.

Return
string10-space indented help to use the command.

final public function setConduitURI($conduit_uri)

Set the URI which the workflow will open a conduit connection to when establishConduit() is called. Arcanist makes an effort to set this by default for all workflows (by reading .arcconfig and/or the value of --conduit-uri) even if they don't need Conduit, so a workflow can generally upgrade into a conduit workflow later by just calling establishConduit().

You generally should not need to call this method unless you are specifically overriding the default URI. It is normally sufficient to just invoke establishConduit().

NOTE: You can not call this after a conduit has been established.
Parameters
string$conduit_uriThe URI to open a conduit to when @{method:establishConduit} is called.
Return
this

final public function getConduitURI()

Returns the URI the conduit connection within the workflow uses.

Return
string

final public function establishConduit()

Open a conduit channel to the server which was previously configured by calling setConduitURI(). Arcanist will do this automatically if the workflow returns true from requiresConduit(), or you can later upgrade a workflow and build a conduit by invoking it manually.

You must establish a conduit before you can make conduit calls.

NOTE: You must call setConduitURI() before you can call this method.
Return
this

final public function getConfigFromAnySource($key)

This method is not documented.
Parameters
$key
Return
wild

final public function setConduitCredentials($credentials)

Set credentials which will be used to authenticate against Conduit. These credentials can then be used to establish an authenticated connection to conduit by calling authenticateConduit(). Arcanist sets some defaults for all workflows regardless of whether or not they return true from requireAuthentication(), based on the ~/.arcrc and

.arcconf## files if they are present. Thus, you can generally upgrade a

workflow which does not require authentication into an authenticated workflow by later invoking requireAuthentication(). You should not normally need to call this method unless you are specifically overriding the defaults.

NOTE: You can not call this method after calling authenticateConduit().
Parameters
dict$credentialsA credential dictionary, see @{method:authenticateConduit}.
Return
this

final public function forceConduitVersion($version)

Force arc to identify with a specific Conduit version during the protocol handshake. This is primarily useful for development (especially for sending diffs which bump the client Conduit version), since the client still actually speaks the builtin version of the protocol.

Controlled by the --conduit-version flag.

Parameters
int$versionVersion the client should pretend to be.
Return
this

final public function getConduitVersion()

Get the protocol version the client should identify with.

Return
intVersion the client should claim to be.

final public function setConduitTimeout($timeout)

Override the default timeout for Conduit.

Controlled by the --conduit-timeout flag.

Parameters
float$timeoutTimeout, in seconds.
Return
this

final public function authenticateConduit()

Open and authenticate a conduit connection to a Phabricator server using provided credentials. Normally, Arcanist does this for you automatically when you return true from requiresAuthentication(), but you can also upgrade an existing workflow to one with an authenticated conduit by invoking this method manually.

You must authenticate the conduit before you can make authenticated conduit calls (almost all calls require authentication).

This method uses credentials provided via setConduitCredentials() to authenticate to the server:

  • user (required) The username to authenticate with.
  • certificate (required) The Conduit certificate to use.
  • description (optional) Description of the invoking command.

Successful authentication allows you to call getUserPHID() and getUserName(), as well as use the client you access with getConduit() to make authenticated calls.

NOTE: You must call setConduitURI() and setConduitCredentials() before you invoke this method.
Return
this

final protected function isConduitAuthenticated()

This method is not documented.
Return
boolTrue if conduit is authenticated, false otherwise.

public function requiresConduit()

Override this to return true if your workflow requires a conduit channel. Arc will build the channel for you before your workflow executes. This implies that you only need an unauthenticated channel; if you need authentication, override requiresAuthentication().

Return
boolTrue if arc should build a conduit channel before running the workflow.

public function requiresAuthentication()

Override this to return true if your workflow requires an authenticated conduit channel. This implies that it requires a conduit. Arc will build and authenticate the channel for you before the workflow executes.

Return
boolTrue if arc should build an authenticated conduit channel before running the workflow.

final public function getUserPHID()

Returns the PHID for the user once they've authenticated via Conduit.

Return
phidAuthenticated user PHID.

final public function getUserName()

Return the username for the user once they've authenticated via Conduit.

Return
stringAuthenticated username.

final public function getConduit()

Get the established ConduitClient in order to make Conduit method calls. Before the client is available it must be connected, either implicitly by making requireConduit() or requireAuthentication() return true, or explicitly by calling establishConduit() or authenticateConduit().

Return
@{class@libphutil:ConduitClient}Live conduit client.

final public function setArcanistConfiguration($arcanist_configuration)

This method is not documented.
Parameters
ArcanistConfiguration$arcanist_configuration
Return
wild

final public function getArcanistConfiguration()

This method is not documented.
Return
wild

final public function setConfigurationManager($arcanist_configuration_manager)

This method is not documented.
Parameters
ArcanistConfigurationManager$arcanist_configuration_manager
Return
wild

final public function getConfigurationManager()

This method is not documented.
Return
wild

public function requiresWorkingCopy()

This method is not documented.
Return
wild

public function desiresWorkingCopy()

This method is not documented.
Return
wild

public function requiresRepositoryAPI()

This method is not documented.
Return
wild

public function desiresRepositoryAPI()

This method is not documented.
Return
wild

final public function setCommand($command)

This method is not documented.
Parameters
$command
Return
wild

final public function getCommand()

This method is not documented.
Return
wild

public function getArguments()

This method is not documented.
Return
wild

final public function setWorkingDirectory($working_directory)

This method is not documented.
Parameters
$working_directory
Return
wild

final public function getWorkingDirectory()

This method is not documented.
Return
wild

final private function setParentWorkflow($parent_workflow)

This method is not documented.
Parameters
$parent_workflow
Return
wild

final protected function getParentWorkflow()

This method is not documented.
Return
wild

final public function buildChildWorkflow($command, $argv)

This method is not documented.
Parameters
$command
array$argv
Return
wild

final public function getArgument($key, $default)

This method is not documented.
Parameters
$key
$default
Return
wild

final public function getPassedArguments()

This method is not documented.
Return
wild

final public function getCompleteArgumentSpecification()

This method is not documented.
Return
wild

final public function parseArguments($args)

This method is not documented.
Parameters
array$args
Return
wild

protected function didParseArguments()

This method is not documented.
Return
wild

final public function getWorkingCopy()

This method is not documented.
Return
wild

final public function setRepositoryAPI($api)

This method is not documented.
Parameters
$api
Return
wild

final public function hasRepositoryAPI()

This method is not documented.
Return
wild

final public function getRepositoryAPI()

This method is not documented.
Return
wild

final protected function shouldRequireCleanUntrackedFiles()

This method is not documented.
Return
wild

final public function setCommitMode($mode)

This method is not documented.
Parameters
$mode
Return
wild

final public function finalizeWorkingCopy()

This method is not documented.
Return
wild

final public function requireCleanWorkingCopy()

This method is not documented.
Return
wild

private function getShouldAmend()

This method is not documented.
Return
wild

private function calculateShouldAmend()

This method is not documented.
Return
wild

private function askForAdd($files)

This method is not documented.
Parameters
array$files
Return
wild

private function getAskForAddPrompt($files)

This method is not documented.
Parameters
array$files
Return
wild

final protected function loadDiffBundleFromConduit($conduit, $diff_id)

This method is not documented.
Parameters
ConduitClient$conduit
$diff_id
Return
wild

final protected function loadRevisionBundleFromConduit($conduit, $revision_id)

This method is not documented.
Parameters
ConduitClient$conduit
$revision_id
Return
wild

final private function loadBundleFromConduit($conduit, $params)

This method is not documented.
Parameters
ConduitClient$conduit
$params
Return
wild

final protected function getChangedLines($path, $mode)

Return a list of lines changed by the current diff, or null if the change list is meaningless (for example, because the path is a directory or binary file).

Parameters
string$pathPath within the repository.
string$modeChange selection mode (see ArcanistDiffHunk).
Return
list|nullList of changed line numbers, or null to indicate that the path is not a line-oriented text file.

final protected function getChange($path)

This method is not documented.
Parameters
$path
Return
wild

final public function willRunWorkflow()

This method is not documented.
Return
wild

final protected function normalizeRevisionID($revision_id)

This method is not documented.
Parameters
$revision_id
Return
wild

protected function shouldShellComplete()

This method is not documented.
Return
wild

protected function getShellCompletions($argv)

This method is not documented.
Parameters
array$argv
Return
wild
This method is not documented.
Return
wild

final protected function getPassthruArgumentsAsMap($command)

This method is not documented.
Parameters
$command
Return
wild

final protected function getPassthruArgumentsAsArgv($command)

This method is not documented.
Parameters
$command
Return
wild

final protected function writeStatusMessage($msg)

Write a message to stderr so that '--json' flags or stdout which is meant to be piped somewhere aren't disrupted.

Parameters
string$msgMessage to write to stderr.
Return
void

final public function writeInfo($title, $message)

This method is not documented.
Parameters
$title
$message
Return
wild

final public function writeWarn($title, $message)

This method is not documented.
Parameters
$title
$message
Return
wild

final public function writeOkay($title, $message)

This method is not documented.
Parameters
$title
$message
Return
wild

final protected function isHistoryImmutable()

This method is not documented.
Return
wild

final protected function selectPathsForWorkflow($paths, $rev, $omit_mask)

Workflows like 'lint' and 'unit' operate on a list of working copy paths. The user can either specify the paths explicitly ("a.js b.php"), or by specifying a revision ("--rev a3f10f1f") to select all paths modified since that revision, or by omitting both and letting arc choose the default relative revision.

This method takes the user's selections and returns the paths that the workflow should act upon.

Parameters
list$pathsList of explicitly provided paths.
string|null$revRevision name, if provided.
mask$omit_maskMask of ArcanistRepositoryAPI flags to exclude. Defaults to ArcanistRepositoryAPI::FLAG_UNTRACKED.
Return
listList of paths the workflow should act on.

final protected function renderRevisionList($revisions)

This method is not documented.
Parameters
array$revisions
Return
wild

final protected function readScratchFile($path)

Try to read a scratch file, if it exists and is readable.

Parameters
string$pathScratch file name.
Return
mixedString for file contents, or false for failure.

final protected function readScratchJSONFile($path)

Try to read a scratch JSON file, if it exists and is readable.

Parameters
string$pathScratch file name.
Return
arrayEmpty array for failure.

final protected function writeScratchFile($path, $data)

Try to write a scratch file, if there's somewhere to put it and we can write there.

Parameters
string$pathScratch file name to write.
string$dataData to write.
Return
boolTrue on success, false on failure.

final protected function writeScratchJSONFile($path, $data)

Try to write a scratch JSON file, if there's somewhere to put it and we can write there.

Parameters
string$pathScratch file name to write.
array$dataData to write.
Return
boolTrue on success, false on failure.

final protected function removeScratchFile($path)

Try to remove a scratch file.

Parameters
string$pathScratch file name to remove.
Return
boolTrue if the file was removed successfully.

final protected function getReadableScratchFilePath($path)

Get a human-readable description of the scratch file location.

Parameters
string$pathScratch file name.
Return
mixedString, or false on failure.

final protected function getScratchFilePath($path)

Get the path to a scratch file, if possible.

Parameters
string$pathScratch file name.
Return
mixedFile path, or false on failure.

final protected function getRepositoryEncoding()

This method is not documented.
Return
wild

final protected function loadProjectRepository()

This method is not documented.
Return
wild

final protected function newInteractiveEditor($text)

This method is not documented.
Parameters
$text
Return
wild

final protected function newDiffParser()

This method is not documented.
Return
wild

final protected function resolveCall($method, $timeout)

This method is not documented.
Parameters
ConduitFuture$method
$timeout
Return
wild

final protected function dispatchEvent($type, $data)

This method is not documented.
Parameters
$type
array$data
Return
wild

final public function parseBaseCommitArgument($argv)

This method is not documented.
Parameters
array$argv
Return
wild

final protected function getRepositoryVersion()

This method is not documented.
Return
wild

final protected function getRepositoryPHID()

Get the PHID of the Phabricator repository this working copy corresponds to. Returns null if no repository can be identified.

Return
phid|nullRepository PHID, or null if no repository can be identified.

final protected function getRepositoryName()

Get the name of the Phabricator repository this working copy corresponds to. Returns null if no repository can be identified.

Return
string|nullRepository name, or null if no repository can be identified.

final protected function getRepositoryURI()

Get the URI of the Phabricator repository this working copy corresponds to. Returns null if no repository can be identified.

Return
string|nullRepository URI, or null if no repository can be identified.

final protected function getRepositoryStagingConfiguration()

This method is not documented.
Return
wild

final protected function getRepositoryReasons()

Get human-readable reasoning explaining how arc evaluated which Phabricator repository corresponds to this working copy. Used by arc which to explain the process to users.

Return
list<string>Human-readable explanation of the repository association process.

private function getRepositoryInformation()

This method is not documented.
Return
wild

private function loadRepositoryInformation()

This method is not documented.
Return
wild

private function getRepositoryQuery()

This method is not documented.
Return
wild

protected function newLintEngine($engine_class)

Build a new lint engine for the current working copy.

Optionally, you can pass an explicit engine class name to build an engine of a particular class. Normally this is used to implement an --engine flag from the CLI.

Parameters
string$engine_classOptional explicit engine class name.
Return
ArcanistLintEngineConstructed engine.

protected function newUnitTestEngine($engine_class)

Build a new unit test engine for the current working copy.

Optionally, you can pass an explicit engine class name to build an engine of a particular class. Normally this is used to implement an --engine flag from the CLI.

Parameters
string$engine_classOptional explicit engine class name.
Return
ArcanistUnitTestEngineConstructed engine.

protected function openURIsInBrowser($uris)

This method is not documented.
Parameters
array$uris
Return
wild

private function getBrowserCommand()

This method is not documented.
Return
wild

protected function askForRepositoryUpdate()

Ask Phabricator to update the current repository as soon as possible.

Calling this method after pushing commits allows Phabricator to discover the commits more quickly, so the system overall is more responsive.

Return
void

protected function getModernLintDictionary($map)

This method is not documented.
Parameters
array$map
Return
wild

protected function getModernUnitDictionary($map)

This method is not documented.
Parameters
array$map
Return
wild

private function getModernCommonDictionary($map)

This method is not documented.
Parameters
array$map
Return
wild