| 1 |
<?xml version="1.0" encoding="utf-8"?> |
| 2 |
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| 3 |
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> |
| 4 |
<head> |
| 5 |
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> |
| 6 |
<meta name="generator" content="Docutils 0.21.2: https://docutils.sourceforge.io/" /> |
| 7 |
<title>phabricator</title> |
| 8 |
<link rel="stylesheet" href="../style.css" type="text/css" /> |
| 9 |
</head> |
| 10 |
<body> |
| 11 |
<div class="document" id="phabricator"> |
| 12 |
<span id="ext-phabricator"></span> |
| 13 |
<h1 class="title">phabricator</h1> |
| 14 |
|
| 15 |
<div class="contents htmlonly topic" id="contents"> |
| 16 |
<p class="topic-title"><a class="reference internal" href="#top">Contents</a></p> |
| 17 |
<ul class="simple"> |
| 18 |
<li><a class="reference internal" href="#description" id="toc-entry-1">Description</a></li> |
| 19 |
<li><a class="reference internal" href="#commands" id="toc-entry-2">Commands</a><ul> |
| 20 |
<li><a class="reference internal" href="#change-import-export" id="toc-entry-3">Change import/export</a></li> |
| 21 |
</ul> |
| 22 |
</li> |
| 23 |
</ul> |
| 24 |
</div> |
| 25 |
<p>simple Phabricator integration (EXPERIMENTAL)</p> |
| 26 |
<div class="section" id="description"> |
| 27 |
<h1><a class="toc-backref" href="#contents">Description</a></h1> |
| 28 |
<p>This extension provides a <tt class="docutils literal">phabsend</tt> command which sends a stack of |
| 29 |
changesets to Phabricator, and a <tt class="docutils literal">phabread</tt> command which prints a stack of |
| 30 |
revisions in a format suitable for <a class="reference external" href="hg-import.html"><tt class="docutils literal">hg import</tt></a>, and a <tt class="docutils literal">phabupdate</tt> command |
| 31 |
to update statuses in batch.</p> |
| 32 |
<p>A "phabstatus" view for <a class="reference external" href="hg-show.html"><tt class="docutils literal">hg show</tt></a> is also provided; it displays status |
| 33 |
information of Phabricator differentials associated with unfinished |
| 34 |
changesets.</p> |
| 35 |
<p>By default, Phabricator requires <tt class="docutils literal">Test Plan</tt> which might prevent some |
| 36 |
changeset from being sent. The requirement could be disabled by changing |
| 37 |
<tt class="docutils literal"><span class="pre">differential.require-test-plan-field</span></tt> config server side.</p> |
| 38 |
<p>Config:</p> |
| 39 |
<pre class="literal-block"> |
| 40 |
[phabricator] |
| 41 |
# Phabricator URL |
| 42 |
url = https://phab.example.com/ |
| 43 |
|
| 44 |
# Repo callsign. If a repo has a URL https://$HOST/diffusion/FOO, then its |
| 45 |
# callsign is "FOO". |
| 46 |
callsign = FOO |
| 47 |
|
| 48 |
# curl command to use. If not set (default), use builtin HTTP library to |
| 49 |
# communicate. If set, use the specified curl command. This could be useful |
| 50 |
# if you need to specify advanced options that is not easily supported by |
| 51 |
# the internal library. |
| 52 |
curlcmd = curl --connect-timeout 2 --retry 3 --silent |
| 53 |
|
| 54 |
# retry failed command N time (default 0). Useful when using the extension |
| 55 |
# over flakly connection. |
| 56 |
# |
| 57 |
# We wait `retry.interval` between each retry, in seconds. |
| 58 |
# (default 1 second). |
| 59 |
retry = 3 |
| 60 |
retry.interval = 10 |
| 61 |
|
| 62 |
# the retry option can combine well with the http.timeout one. |
| 63 |
# |
| 64 |
# For example to give up on http request after 20 seconds: |
| 65 |
[http] |
| 66 |
timeout=20 |
| 67 |
|
| 68 |
[auth] |
| 69 |
example.schemes = https |
| 70 |
example.prefix = phab.example.com |
| 71 |
|
| 72 |
# API token. Get it from https://$HOST/conduit/login/ |
| 73 |
example.phabtoken = cli-xxxxxxxxxxxxxxxxxxxxxxxxxxxx |
| 74 |
</pre> |
| 75 |
</div> |
| 76 |
<div class="section" id="commands"> |
| 77 |
<h1><a class="toc-backref" href="#contents">Commands</a></h1> |
| 78 |
<div class="section" id="change-import-export"> |
| 79 |
<h2><a class="toc-backref" href="#contents">Change import/export</a></h2> |
| 80 |
<div class="section" id="phabimport"> |
| 81 |
<h3>phabimport</h3> |
| 82 |
<p>import patches from Phabricator for the specified Differential Revisions:</p> |
| 83 |
<pre class="literal-block"> |
| 84 |
hg phabimport DREVSPEC... [OPTIONS] |
| 85 |
</pre> |
| 86 |
<p>The patches are read and applied starting at the parent of the working |
| 87 |
directory.</p> |
| 88 |
<p>See <tt class="docutils literal">hg help phabread</tt> for how to specify DREVSPEC.</p> |
| 89 |
<p>Options:</p> |
| 90 |
<table class="docutils option-list" frame="void" rules="none"> |
| 91 |
<col class="option" /> |
| 92 |
<col class="description" /> |
| 93 |
<tbody valign="top"> |
| 94 |
<tr><td class="option-group"> |
| 95 |
<kbd><span class="option">--stack</span></kbd></td> |
| 96 |
<td>import dependencies as well</td></tr> |
| 97 |
<tr><td class="option-group" colspan="2"> |
| 98 |
<kbd><span class="option">--test-vcr <var><VALUE></var></span></kbd></td> |
| 99 |
</tr> |
| 100 |
<tr><td> </td><td>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)</td></tr> |
| 101 |
</tbody> |
| 102 |
</table> |
| 103 |
</div> |
| 104 |
<div class="section" id="phabread"> |
| 105 |
<h3>phabread</h3> |
| 106 |
<p>print patches from Phabricator suitable for importing:</p> |
| 107 |
<pre class="literal-block"> |
| 108 |
hg phabread DREVSPEC... [OPTIONS] |
| 109 |
</pre> |
| 110 |
<p>DREVSPEC could be a Differential Revision identity, like <tt class="docutils literal">D123</tt>, or just |
| 111 |
the number <tt class="docutils literal">123</tt>. It could also have common operators like <tt class="docutils literal">+</tt>, <tt class="docutils literal">-</tt>, |
| 112 |
<tt class="docutils literal">&</tt>, <tt class="docutils literal">(</tt>, <tt class="docutils literal">)</tt> for complex queries. Prefix <tt class="docutils literal">:</tt> could be used to |
| 113 |
select a stack. If multiple DREVSPEC values are given, the result is the |
| 114 |
union of each individually evaluated value. No attempt is currently made |
| 115 |
to reorder the values to run from parent to child.</p> |
| 116 |
<p><tt class="docutils literal">abandoned</tt>, <tt class="docutils literal">accepted</tt>, <tt class="docutils literal">closed</tt>, <tt class="docutils literal">needsreview</tt>, <tt class="docutils literal">needsrevision</tt> |
| 117 |
could be used to filter patches by status. For performance reason, they |
| 118 |
only represent a subset of non-status selections and cannot be used alone.</p> |
| 119 |
<p>For example, <tt class="docutils literal"><span class="pre">:D6+8-(2+D4)</span></tt> selects a stack up to D6, plus D8 and exclude |
| 120 |
D2 and D4. <tt class="docutils literal">:D9 & needsreview</tt> selects "Needs Review" revisions in a |
| 121 |
stack up to D9.</p> |
| 122 |
<p>If --stack is given, follow dependencies information and read all patches. |
| 123 |
It is equivalent to the <tt class="docutils literal">:</tt> operator.</p> |
| 124 |
<p>Options:</p> |
| 125 |
<table class="docutils option-list" frame="void" rules="none"> |
| 126 |
<col class="option" /> |
| 127 |
<col class="description" /> |
| 128 |
<tbody valign="top"> |
| 129 |
<tr><td class="option-group"> |
| 130 |
<kbd><span class="option">--stack</span></kbd></td> |
| 131 |
<td>read dependencies</td></tr> |
| 132 |
<tr><td class="option-group" colspan="2"> |
| 133 |
<kbd><span class="option">--test-vcr <var><VALUE></var></span></kbd></td> |
| 134 |
</tr> |
| 135 |
<tr><td> </td><td>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)</td></tr> |
| 136 |
</tbody> |
| 137 |
</table> |
| 138 |
</div> |
| 139 |
<div class="section" id="phabsend"> |
| 140 |
<h3>phabsend</h3> |
| 141 |
<p>upload changesets to Phabricator:</p> |
| 142 |
<pre class="literal-block"> |
| 143 |
hg phabsend REV [OPTIONS] |
| 144 |
</pre> |
| 145 |
<p>If there are multiple revisions specified, they will be send as a stack |
| 146 |
with a linear dependencies relationship using the order specified by the |
| 147 |
revset.</p> |
| 148 |
<p>For the first time uploading changesets, local tags will be created to |
| 149 |
maintain the association. After the first time, phabsend will check |
| 150 |
obsstore and tags information so it can figure out whether to update an |
| 151 |
existing Differential Revision, or create a new one.</p> |
| 152 |
<p>If --amend is set, update commit messages so they have the |
| 153 |
<tt class="docutils literal">Differential Revision</tt> URL, remove related tags. This is similar to what |
| 154 |
arcanist will do, and is more desired in author-push workflows. Otherwise, |
| 155 |
use local tags to record the <tt class="docutils literal">Differential Revision</tt> association.</p> |
| 156 |
<p>The --confirm option lets you confirm changesets before sending them. You |
| 157 |
can also add following to your configuration file to make it default |
| 158 |
behaviour:</p> |
| 159 |
<pre class="literal-block"> |
| 160 |
[phabsend] |
| 161 |
confirm = true |
| 162 |
</pre> |
| 163 |
<p>By default, a separate review will be created for each commit that is |
| 164 |
selected, and will have the same parent/child relationship in Phabricator. |
| 165 |
If <tt class="docutils literal"><span class="pre">--fold</span></tt> is set, multiple commits are rolled up into a single review |
| 166 |
as if diffed from the parent of the first revision to the last. The commit |
| 167 |
messages are concatenated in the summary field on Phabricator.</p> |
| 168 |
<p>phabsend will check obsstore and the above association to decide whether to |
| 169 |
update an existing Differential Revision, or create a new one.</p> |
| 170 |
<p>Options:</p> |
| 171 |
<table class="docutils option-list" frame="void" rules="none"> |
| 172 |
<col class="option" /> |
| 173 |
<col class="description" /> |
| 174 |
<tbody valign="top"> |
| 175 |
<tr><td class="option-group" colspan="2"> |
| 176 |
<kbd><span class="option">-r</span>, <span class="option">--rev <var><REV[+]></var></span></kbd></td> |
| 177 |
</tr> |
| 178 |
<tr><td> </td><td>revisions to send</td></tr> |
| 179 |
<tr><td class="option-group"> |
| 180 |
<kbd><span class="option">--amend</span></kbd></td> |
| 181 |
<td>update commit messages (default: True)</td></tr> |
| 182 |
<tr><td class="option-group" colspan="2"> |
| 183 |
<kbd><span class="option">--reviewer <var><VALUE[+]></var></span></kbd></td> |
| 184 |
</tr> |
| 185 |
<tr><td> </td><td>specify reviewers</td></tr> |
| 186 |
<tr><td class="option-group" colspan="2"> |
| 187 |
<kbd><span class="option">--blocker <var><VALUE[+]></var></span></kbd></td> |
| 188 |
</tr> |
| 189 |
<tr><td> </td><td>specify blocking reviewers</td></tr> |
| 190 |
<tr><td class="option-group" colspan="2"> |
| 191 |
<kbd><span class="option">-m</span>, <span class="option">--comment <var><VALUE></var></span></kbd></td> |
| 192 |
</tr> |
| 193 |
<tr><td> </td><td>add a comment to Revisions with new/updated Diffs</td></tr> |
| 194 |
<tr><td class="option-group"> |
| 195 |
<kbd><span class="option">--confirm</span></kbd></td> |
| 196 |
<td>ask for confirmation before sending</td></tr> |
| 197 |
<tr><td class="option-group"> |
| 198 |
<kbd><span class="option">--fold</span></kbd></td> |
| 199 |
<td>combine the revisions into one review</td></tr> |
| 200 |
<tr><td class="option-group" colspan="2"> |
| 201 |
<kbd><span class="option">--test-vcr <var><VALUE></var></span></kbd></td> |
| 202 |
</tr> |
| 203 |
<tr><td> </td><td>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)</td></tr> |
| 204 |
</tbody> |
| 205 |
</table> |
| 206 |
<p>[+] marked option can be specified multiple times</p> |
| 207 |
</div> |
| 208 |
<div class="section" id="phabupdate"> |
| 209 |
<h3>phabupdate</h3> |
| 210 |
<p>update Differential Revision in batch:</p> |
| 211 |
<pre class="literal-block"> |
| 212 |
hg phabupdate [DREVSPEC...| -r REV...] [OPTIONS] |
| 213 |
</pre> |
| 214 |
<p>DREVSPEC selects revisions. See <a class="reference external" href="hg.1.html#phabread"><tt class="docutils literal">hg help phabread</tt></a> for its usage.</p> |
| 215 |
<p>Options:</p> |
| 216 |
<table class="docutils option-list" frame="void" rules="none"> |
| 217 |
<col class="option" /> |
| 218 |
<col class="description" /> |
| 219 |
<tbody valign="top"> |
| 220 |
<tr><td class="option-group"> |
| 221 |
<kbd><span class="option">--accept</span></kbd></td> |
| 222 |
<td>accept revisions</td></tr> |
| 223 |
<tr><td class="option-group"> |
| 224 |
<kbd><span class="option">--reject</span></kbd></td> |
| 225 |
<td>reject revisions</td></tr> |
| 226 |
<tr><td class="option-group" colspan="2"> |
| 227 |
<kbd><span class="option">--request-review</span></kbd></td> |
| 228 |
</tr> |
| 229 |
<tr><td> </td><td>request review on revisions</td></tr> |
| 230 |
<tr><td class="option-group"> |
| 231 |
<kbd><span class="option">--abandon</span></kbd></td> |
| 232 |
<td>abandon revisions</td></tr> |
| 233 |
<tr><td class="option-group"> |
| 234 |
<kbd><span class="option">--reclaim</span></kbd></td> |
| 235 |
<td>reclaim revisions</td></tr> |
| 236 |
<tr><td class="option-group"> |
| 237 |
<kbd><span class="option">--close</span></kbd></td> |
| 238 |
<td>close revisions</td></tr> |
| 239 |
<tr><td class="option-group"> |
| 240 |
<kbd><span class="option">--reopen</span></kbd></td> |
| 241 |
<td>reopen revisions</td></tr> |
| 242 |
<tr><td class="option-group"> |
| 243 |
<kbd><span class="option">--plan-changes</span></kbd></td> |
| 244 |
<td>plan changes for revisions</td></tr> |
| 245 |
<tr><td class="option-group"> |
| 246 |
<kbd><span class="option">--resign</span></kbd></td> |
| 247 |
<td>resign as a reviewer from revisions</td></tr> |
| 248 |
<tr><td class="option-group"> |
| 249 |
<kbd><span class="option">--commandeer</span></kbd></td> |
| 250 |
<td>commandeer revisions</td></tr> |
| 251 |
<tr><td class="option-group" colspan="2"> |
| 252 |
<kbd><span class="option">-m</span>, <span class="option">--comment <var><VALUE></var></span></kbd></td> |
| 253 |
</tr> |
| 254 |
<tr><td> </td><td>comment on the last revision</td></tr> |
| 255 |
<tr><td class="option-group" colspan="2"> |
| 256 |
<kbd><span class="option">-r</span>, <span class="option">--rev <var><REV></var></span></kbd></td> |
| 257 |
</tr> |
| 258 |
<tr><td> </td><td>local revision to update</td></tr> |
| 259 |
<tr><td class="option-group" colspan="2"> |
| 260 |
<kbd><span class="option">--test-vcr <var><VALUE></var></span></kbd></td> |
| 261 |
</tr> |
| 262 |
<tr><td> </td><td>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)</td></tr> |
| 263 |
</tbody> |
| 264 |
</table> |
| 265 |
</div> |
| 266 |
</div> |
| 267 |
</div> |
| 268 |
</div> |
| 269 |
</body> |
| 270 |
</html> |