# phabricator

Contents

- Description
- Commands
  - Change import/export

simple Phabricator integration (EXPERIMENTAL)

# Description

This extension provides a `phabsend` command which sends a stack of changesets to Phabricator, and a `phabread` command which prints a stack of revisions in a format suitable for `hg import`, and a `phabupdate` command to update statuses in batch.

A "phabstatus" view for `hg show` is also provided; it displays status information of Phabricator differentials associated with unfinished changesets.

By default, Phabricator requires `Test Plan` which might prevent some changeset from being sent. The requirement could be disabled by changing `differential.require-test-plan-field` config server side.

Config:

    [phabricator]
    # Phabricator URL
    url = https://phab.example.com/

    # Repo callsign. If a repo has a URL https://$HOST/diffusion/FOO, then its
    # callsign is "FOO".
    callsign = FOO

    # curl command to use. If not set (default), use builtin HTTP library to
    # communicate. If set, use the specified curl command. This could be useful
    # if you need to specify advanced options that is not easily supported by
    # the internal library.
    curlcmd = curl --connect-timeout 2 --retry 3 --silent

    # retry failed command N time (default 0). Useful when using the extension
    # over flakly connection.
    #
    # We wait `retry.interval` between each retry, in seconds.
    # (default 1 second).
    retry = 3
    retry.interval = 10

    # the retry option can combine well with the http.timeout one.
    #
    # For example to give up on http request after 20 seconds:
    [http]
    timeout=20

    [auth]
    example.schemes = https
    example.prefix = phab.example.com

    # API token. Get it from https://$HOST/conduit/login/
    example.phabtoken = cli-xxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Commands

## Change import/export

### phabimport

import patches from Phabricator for the specified Differential Revisions:

    hg phabimport DREVSPEC... [OPTIONS]

The patches are read and applied starting at the parent of the working directory.

See `hg help phabread` for how to specify DREVSPEC.

Options:

`--stack` | import dependencies as well
`--test-vcr <VALUE>`
| Path to a vcr file. If nonexistent, will record a new vcr transcript, otherwise will mock all http requests using the specified vcr file. (ADVANCED)

### phabread

print patches from Phabricator suitable for importing:

    hg phabread DREVSPEC... [OPTIONS]

DREVSPEC could be a Differential Revision identity, like `D123`, or just the number `123`. It could also have common operators like `+`, `-`, `&`, `(`, `)` for complex queries. Prefix `:` could be used to select a stack. If multiple DREVSPEC values are given, the result is the union of each individually evaluated value. No attempt is currently made to reorder the values to run from parent to child.

`abandoned`, `accepted`, `closed`, `needsreview`, `needsrevision` could be used to filter patches by status. For performance reason, they only represent a subset of non-status selections and cannot be used alone.

For example, `:D6+8-(2+D4)` selects a stack up to D6, plus D8 and exclude D2 and D4. `:D9 & needsreview` selects "Needs Review" revisions in a stack up to D9.

If --stack is given, follow dependencies information and read all patches. It is equivalent to the `:` operator.

Options:

`--stack` | read dependencies
`--test-vcr <VALUE>`
| Path to a vcr file. If nonexistent, will record a new vcr transcript, otherwise will mock all http requests using the specified vcr file. (ADVANCED)

### phabsend

upload changesets to Phabricator:

    hg phabsend REV [OPTIONS]

If there are multiple revisions specified, they will be send as a stack with a linear dependencies relationship using the order specified by the revset.

For the first time uploading changesets, local tags will be created to maintain the association. After the first time, phabsend will check obsstore and tags information so it can figure out whether to update an existing Differential Revision, or create a new one.

If --amend is set, update commit messages so they have the `Differential Revision` URL, remove related tags. This is similar to what arcanist will do, and is more desired in author-push workflows. Otherwise, use local tags to record the `Differential Revision` association.

The --confirm option lets you confirm changesets before sending them. You can also add following to your configuration file to make it default behaviour:

    [phabsend]
    confirm = true

By default, a separate review will be created for each commit that is selected, and will have the same parent/child relationship in Phabricator. If `--fold` is set, multiple commits are rolled up into a single review as if diffed from the parent of the first revision to the last. The commit messages are concatenated in the summary field on Phabricator.

phabsend will check obsstore and the above association to decide whether to update an existing Differential Revision, or create a new one.

Options:

`-r, --rev <REV[+]>`
| revisions to send
`--amend` | update commit messages (default: True)
`--reviewer <VALUE[+]>`
| specify reviewers
`--blocker <VALUE[+]>`
| specify blocking reviewers
`-m, --comment <VALUE>`
| add a comment to Revisions with new/updated Diffs
`--confirm` | ask for confirmation before sending
`--fold` | combine the revisions into one review
`--test-vcr <VALUE>`
| Path to a vcr file. If nonexistent, will record a new vcr transcript, otherwise will mock all http requests using the specified vcr file. (ADVANCED)

[+] marked option can be specified multiple times

### phabupdate

update Differential Revision in batch:

    hg phabupdate [DREVSPEC...| -r REV...] [OPTIONS]

DREVSPEC selects revisions. See `hg help phabread` for its usage.

Options:

`--accept` | accept revisions
`--reject` | reject revisions
`--request-review`
| request review on revisions
`--abandon` | abandon revisions
`--reclaim` | reclaim revisions
`--close` | close revisions
`--reopen` | reopen revisions
`--plan-changes` | plan changes for revisions
`--resign` | resign as a reviewer from revisions
`--commandeer` | commandeer revisions
`-m, --comment <VALUE>`
| comment on the last revision
`-r, --rev <REV>`
| local revision to update
`--test-vcr <VALUE>`
| Path to a vcr file. If nonexistent, will record a new vcr transcript, otherwise will mock all http requests using the specified vcr file. (ADVANCED)