Class ArcanistBaseWorkflow

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.

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.

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.

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

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.

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).

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

Return console formatted string with all command synopses.

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().

Returns the URI the conduit connection within the workflow uses.

Get the protocol version the client should identify with.

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

Get the path to a scratch file, if possible.

Deprecated. See getUserPHID().

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

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

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

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

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

Try to remove a scratch file.

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.

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().

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 specfifying 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.

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.

Override the default timeout for Conduit.

Controlled by the --conduit-timeout flag.

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().

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

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

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