Debian Codegraph @

doc/html/ext-phabricator.html

raw
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 &quot;phabstatus&quot; 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 &quot;FOO&quot;.
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>&lt;VALUE&gt;</var></span></kbd></td>
99 </tr>
100 <tr><td>&nbsp;</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">&amp;</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 &amp; needsreview</tt> selects &quot;Needs Review&quot; 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>&lt;VALUE&gt;</var></span></kbd></td>
134 </tr>
135 <tr><td>&nbsp;</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>&lt;REV[+]&gt;</var></span></kbd></td>
177 </tr>
178 <tr><td>&nbsp;</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>&lt;VALUE[+]&gt;</var></span></kbd></td>
184 </tr>
185 <tr><td>&nbsp;</td><td>specify reviewers</td></tr>
186 <tr><td class="option-group" colspan="2">
187 <kbd><span class="option">--blocker <var>&lt;VALUE[+]&gt;</var></span></kbd></td>
188 </tr>
189 <tr><td>&nbsp;</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>&lt;VALUE&gt;</var></span></kbd></td>
192 </tr>
193 <tr><td>&nbsp;</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>&lt;VALUE&gt;</var></span></kbd></td>
202 </tr>
203 <tr><td>&nbsp;</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>&nbsp;</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>&lt;VALUE&gt;</var></span></kbd></td>
253 </tr>
254 <tr><td>&nbsp;</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>&lt;REV&gt;</var></span></kbd></td>
257 </tr>
258 <tr><td>&nbsp;</td><td>local revision to update</td></tr>
259 <tr><td class="option-group" colspan="2">
260 <kbd><span class="option">--test-vcr <var>&lt;VALUE&gt;</var></span></kbd></td>
261 </tr>
262 <tr><td>&nbsp;</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>