Source

cointoss1973.bitbucket.org / thg / manual / 2.4 / extensions.html

Full commit
  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432


<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">


<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    
    <title>8. Extensions &mdash; TortoiseHg 2.4.0 documentation</title>
    
    <link rel="stylesheet" href="_static/default.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '',
        VERSION:     '2.4.0',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true
      };
    </script>
    <script type="text/javascript" src="_static/jquery.js"></script>
    <script type="text/javascript" src="_static/underscore.js"></script>
    <script type="text/javascript" src="_static/doctools.js"></script>
    <link rel="top" title="TortoiseHg 2.4.0 documentation" href="index.html" />
    <link rel="next" title="9. Use with other VCS systems" href="nonhg.html" />
    <link rel="prev" title="7. Patches" href="patches.html" /> 
  </head>
  <body>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="py-modindex.html" title="Python Module Index"
             >modules</a> |</li>
        <li class="right" >
          <a href="nonhg.html" title="9. Use with other VCS systems"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="patches.html" title="7. Patches"
             accesskey="P">previous</a> |</li>
        <li><a href="index.html">TortoiseHg 2.4.0 documentation</a> &raquo;</li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body">
            
  <div class="section" id="module-extensions">
<span id="extensions"></span><h1>8. Extensions<a class="headerlink" href="#module-extensions" title="Permalink to this headline"></a></h1>
<p>This chapter describes Mercurial extensions that are shipped with
TortoiseHg binary packages for Windows.  These external extensions are
included as a convenience to users, so they can be easily enabled as
soon as they are needed.</p>
<div class="section" id="hgfold">
<h2>8.1. Hgfold<a class="headerlink" href="#hgfold" title="Permalink to this headline"></a></h2>
<p><a class="reference external" href="http://mercurial.selenic.com/wiki/CaseFoldExtension">hgfold</a> is a
Mercurial extension that helps Windows users deal with filename case
collisions on VFAT and NTFS.</p>
<p>It adds options to the following Mercurial commands. Type
<strong class="command">hg help &lt;command&gt;</strong> for more information:</p>
<div class="highlight-python"><pre>up    - allows you to update to a revision with filename collisions
merge - allows you to merge with a changeset that would create filename collisions</pre>
</div>
<p>The extension does not currently do anything to prevent filename
collisions. See discussion on the Mercurial Wiki</p>
<p><strong>Installation</strong></p>
<p>To test the use of this plugin, you can specify it on the Mercurial
command line like this:</p>
<div class="highlight-python"><pre>hg --config "extensions.fold=" status</pre>
</div>
<p>You may want to add it to your Mercurial.ini or a repository&#8217;s hgrc like this:</p>
<div class="highlight-python"><pre>[extensions]
fold=</pre>
</div>
<p>If you do this, you can omit the &#8211;config command-line option.</p>
<p><strong>Warnings</strong></p>
<p>Like all merge operations, fold.py has to change the parents of the
working directory. It is still in early testing, so use with caution.</p>
<p>If you get an error about an unknown changeset after running
<strong class="command">hg recover</strong> try
<strong class="command">hg debugsetparents &lt;number of tip revision&gt;</strong>.
You can find the number of the tip revision by running <strong class="command">hg log -l 2</strong>.</p>
</div>
<div class="section" id="perfarce">
<h2>8.2. Perfarce<a class="headerlink" href="#perfarce" title="Permalink to this headline"></a></h2>
<p><a class="reference external" href="http://www.kingswood-consulting.co.uk/hg/perfarce/">Perfarce</a> home
page.</p>
<p>This extension is documented in <a class="reference internal" href="nonhg.html#perfarce-perforce"><em>Perfarce (Perforce)</em></a> section of
<a class="reference internal" href="nonhg.html"><em>Use with other VCS systems</em></a> chapter.</p>
</div>
<div class="section" id="mercurial-keyring">
<h2>8.3. Mercurial-Keyring<a class="headerlink" href="#mercurial-keyring" title="Permalink to this headline"></a></h2>
<ul class="simple">
<li><a class="reference external" href="http://pypi.python.org/pypi/mercurial_keyring">Mercurial Keyring</a> home page</li>
<li><a class="reference external" href="http://mercurial.selenic.com/wiki/KeyringExtension">Keyring Extension</a> wiki page</li>
</ul>
<p>Keyring extension uses services of the keyring library to securely save
authentication passwords (HTTP/HTTPS and SMTP) using system specific
password database (Gnome Keyring, KDE KWallet, OSXKeyChain, dedicated
solutions for Win32 and command line).</p>
<p><strong>What it does</strong></p>
<p>The extension prompts for the HTTP password on the first pull/push
to/from given remote repository (just like it is done by default), but
saves the password (keyed by the combination of username and remote
repository url) in the password database. On the next run it checks for
the username in <tt class="file docutils literal"><span class="pre">.hg/hgrc</span></tt>, then for suitable password in the password
database, and uses those credentials if found.</p>
<p>Similarly, while sending emails via SMTP server which requires
authorization, it prompts for the password on first use of given server,
then saves it in the password database and reuses on successive runs.</p>
<p>In case password turns out incorrect (either because it was invalid, or
because it was changed on the server) it just prompts the user again.</p>
<p><strong>Installation</strong></p>
<p>First, the extension must be enabled in your Mercurial.ini file as:</p>
<div class="highlight-python"><pre>[extensions]
mercurial_keyring=</pre>
</div>
<p><strong>Password backend configuration</strong></p>
<p>The most appropriate password backend should usually be picked automatically,
without configuration. Still, if necessary, it can be configured using
<tt class="file docutils literal"><span class="pre">~/keyringrc.cfg</span></tt> file (<tt class="file docutils literal"><span class="pre">keyringrc.cfg</span></tt> in the home directory of
the current user).
Refer to <a class="reference external" href="http://pypi.python.org/pypi/keyring">keyring docs</a>
for more details.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">On Windows XP and above, your encrypted passwords are stored in the
credentials subsystem using
<a class="reference external" href="http://msdn.microsoft.com/en-us/library/aa374804%28VS.85%29.aspx">CredRead</a> and <a class="reference external" href="http://msdn.microsoft.com/en-us/library/aa375187%28VS.85%29.aspx">CredWrite</a></p>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">On Windows 2K, the encrypted passwords are stored in the system
registry under HKCU\Software\Mercurial\Keyring.</p>
</div>
<p><strong>Repository configuration (HTTP)</strong></p>
<p>Edit repository-local <tt class="file docutils literal"><span class="pre">.hg/hgrc</span></tt> and save there the remote repository
path and the username, but do not save the password. For example:</p>
<div class="highlight-python"><pre>[paths]
myremote = https://my.server.com/hgrepo/someproject

[auth]
myremote.schemes = http https
myremote.prefix = my.server.com/hgrepo
myremote.username = mekk</pre>
</div>
<p>Simpler form with url-embedded name can also be used:</p>
<div class="highlight-python"><pre>[paths]
bitbucket = https://User@bitbucket.org/User/project_name/</pre>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">If both username and password are given in <tt class="file docutils literal"><span class="pre">.hg/hgrc</span></tt>, extension
will use them without using the password database. If username is not
given, extension will prompt for credentials every time, also
without saving the password. So, in both cases, it is effectively
reverting to the default behaviour.</p>
</div>
<p>Consult <a class="reference external" href="http://www.selenic.com/mercurial/hgrc.5.html#auth">[auth]</a>
section documentation for more details.</p>
<p><strong>Repository configuration (SMTP)</strong></p>
<p>Edit either repository-local <tt class="file docutils literal"><span class="pre">.hg/hgrc</span></tt>, or <tt class="file docutils literal"><span class="pre">~/.hgrc</span></tt> (the latter
is usually preferable) and set there all standard email and smtp properties,
including smtp username, but without smtp password. For example:</p>
<div class="highlight-python"><pre>[email]
method = smtp
from = Joe Doe &lt;Joe.Doe@remote.com&gt;

[smtp]
host = smtp.gmail.com
port = 587
username = JoeDoe@gmail.com
tls = true</pre>
</div>
<p>Just as in case of HTTP, you must set username, but must not set password here
to use the extension, in other cases it will revert to the default behaviour.</p>
<p><strong>Usage</strong></p>
<p>Configure the repository as above, then just pull and push (or email) You
should be asked for the password only once (per every username +
remote_repository_url combination).</p>
</div>
<div class="section" id="projrc">
<h2>8.4. projrc<a class="headerlink" href="#projrc" title="Permalink to this headline"></a></h2>
<p><a class="reference external" href="http://mercurial.selenic.com/wiki/ProjrcExtension">projrc</a> is an extension
that makes Mercurial look for and parse .hg/projrc for additional
configuration settings.The file is transferred on clone and on pull
(but never on push), after confirmation by the user, from a list of servers
that &#8216;&#8217;&#8216;must&#8217;&#8216;&#8217; be configured by the user. For security reasons the user
&#8216;&#8217;&#8216;must&#8217;&#8216;&#8217; also select which &#8216;&#8217;<cite>projrc</cite>&#8216;&#8217;  configuration settings will be
transferred (i.e. no settings are transferred from any servers by default).
The user can also configure the extension to automatically accept all changes
to the .hg/projrc file.</p>
<p>This is useful for centralized setups where you want to distribute
configuration settings to all repositories with a minimum amount of setup.
In particular, it can be used to remap subrepository sources, as explained
on Mercurial&#8217;s
<a class="reference external" href="http://mercurial.selenic.com/wiki/SubrepoRemappingPlan">SubrepoRemappingPlan</a>.</p>
<p><strong>Configuration</strong></p>
<p>This extension (as most other extensions) is disabled by default. To use
and configure you must first enable it on the Settings/Extensions panel.</p>
<p>When the extension is enabled you will see a new entry, &#8220;Projrc&#8221; on the
settings dialog. This let&#8217;s you configure the extension by setting the
following settings:</p>
<blockquote>
<div><blockquote>
<div><em class="guilabel">Request confirmation</em>
If True (the default) you&#8217;ll get a prompt whenever
the extension detects changes to the remote server&#8217;s
.hg/projrc file.
If false, the extension will automatically accept any change to the
remote .hg/projrc file.</div></blockquote>
<dl class="docutils">
<dt><em class="guilabel">Servers</em></dt>
<dd>This setting is a comma separated list of glob patterns matching
the server names of the servers that the projrc file will be pulled from.
Unless this setting is set, no .hg/projrc files will be ever
transferred from any servers.</dd>
<dt><em class="guilabel">Include</em></dt>
<dd><p class="first">This key lets you control which sections and which keys will be accepted
from the remote projrc files. This is a a comma separated list of glob
patterns that match the section or key names that will be included.
Keys names must be specified with their section name followed by a &#8216;.&#8217;
followed by the key name (e.g. &#8220;&#8217;&#8216;<cite>diff.git</cite>&#8216;&#8217;&#8221;).</p>
<p class="last">To allow all sections and all keys you can set this setting to &#8220;*&#8221;
(without the quotes).</p>
</dd>
<dt><em class="guilabel">Exclude</em></dt>
<dd><p class="first">This setting is similar to the &#8220;&#8217;&#8216;<cite>Include</cite>&#8216;&#8217;&#8221; setting but it has the
opposite effect. It sets an &#8220;exclude list&#8221; of settings that will not
be transferred from the common projrc files.</p>
<p class="last">The exclude list has the same syntax as the include list. If an exclusion
list is set but the inclusion list is empty or not set all non excluded
keys will be included.</p>
</dd>
<dt><em class="guilabel">Update on incoming</em></dt>
<dd><p class="first">Control whether the .hg/projrc file will be updated on incoming.
It can have the following values:</p>
<ul class="simple">
<li>never: The default. Show whether the remote projrc file has changed,
but do not update (nor ask to update) the local projrc file.</li>
<li>prompt: Look for changes to the projrc file.
If there are changes _always_ show a confirmation prompt,
asking the user if it wants to update its local projrc file.</li>
<li>auto: Look for changes to the projrc file.
Use the value of the &#8220;&#8217;&#8216;<cite>projrc.confirm</cite>&#8216;&#8217;&#8221; configuration key to
determine whether to show a confirmation dialog or not
before updating the local projrc file.</li>
</ul>
<p class="last">If False (the default) you&#8217;ll get a prompt whenever
the extension detects changes to the remote server&#8217;s
.hg/projrc file.
If false, the extension will automatically accept any change to the
remote .hg/projrc file.</p>
</dd>
</dl>
</div></blockquote>
<p>If both an include and an exclude lists are set, and a key matches both
the include and the exclude list, priority is given to the most explicit
key match, in the following order:</p>
<blockquote>
<div><ul class="simple">
<li>full key, exact matches are considered the most explicit (e.g.
&#8220;&#8217;&#8216;<cite>ui.merge</cite>&#8216;&#8217;&#8221;);</li>
<li>pattern (glob) matches are considered next (e.g.
&#8220;&#8217;&#8216;<cite>auth.bitbucket.com.*</cite>&#8216;&#8217;&#8221;), with the longest matching pattern being the
most explicit;</li>
<li>section level matches (e.g. &#8220;&#8217;&#8216;<cite>ui</cite>&#8216;&#8217;&#8221;);</li>
<li>global (&#8220;&#8217;&#8216;<cite>*</cite>&#8216;&#8217;&#8221;) matches.</li>
</ul>
</div></blockquote>
<p>If a key matches both an include and an exclude (glob) pattern of the same
length, the key is &#8216;&#8217;included&#8217;&#8217; (i.e. inclusion takes precedence over
exclusion).</p>
<p><strong>Usage</strong></p>
<p>Once enabled and properly configured, the extension will look for
.hg/projrc files whenever you clone or pull from one of the repositories
specified on its &#8220;servers&#8221; configuration key.</p>
<p>Whenever the extension detects changes to the remote projrc file (e.g. when
you do not have a .hg/projrc file yet, or when the contents of said file
have changed on the server), you&#8217;ll receive a warning unless you have set the
&#8220;Require confirmation&#8221; setting to False (in which case the extension assumes
that you accept the changes). If you accept the changes your local .hg/projrc
file will be updated, and its settings will be taken into account by mercurial
and TortoiseHg.</p>
<p>If a local repository has a .hg/projrc file, you&#8217;ll see an extra panel
on the setting dialog. The title of the extra panel is &#8220;project settings
(.hg/projrc)&#8221;.</p>
<p>The &#8220;project settings&#8221; panel is a read-only panel that shows the settings that
are set on the local .hg/projrc file. Although you can update your local
version of the .hg/projrc file, the panel is read only to indicate that
you cannot change the remote repository&#8217;s settings, and that if the remote
repository settings change your local copy will be updated on the next pull
(if you allow it).</p>
<p>The &#8220;project settings&#8221; settings panel is shown between the &#8220;global settings&#8221; panel
and the &#8220;repository settings&#8221; panel, indicating that its settings are applied
_after_ the global settings but _before_ the local repository settings (i.e
the settings specified in the repository .hg/hgrc file).</p>
<p><strong>Additional Information</strong></p>
<p>For the most up to date information regarding this extension, to see several
detailed usage examples and to learn how to use it and configure it from the
command line, please go to the extension&#8217;s
<a class="reference external" href="http://mercurial.selenic.com/wiki/ProjrcExtension">Wiki</a>.</p>
</div>
<div class="section" id="pbranch">
<h2>8.5. pbranch<a class="headerlink" href="#pbranch" title="Permalink to this headline"></a></h2>
<p>Patch Branches (<a class="reference external" href="http://mercurial.selenic.com/wiki/PatchBranchExtension">pbranch</a>)
is a way to develop a series of patches for submission into a main
repo. It is based on topic branches, one per patch, and is thus highly
suitable for collaborative and/or long-term patch development and
maintenance.</p>
<p><a class="reference external" href="http://arrenbrecht.ch/mercurial/pbranch/">A detailed manual</a> can be found online.</p>
<p>It adds a number of commands which can be listed with
<strong class="command">hg help pbranch</strong>:</p>
<div class="highlight-python"><pre>pbackout       - backs out the current patch branch (undoes all its changes)
pdiff          - prints the final diff for the current or given patch branch
peditmessage   - edit the patch message
pemail         - send patches by email
pexport        - exports patches
pextdiff       - combines pdiff and extdiff
pgraph         - print an ASCII art rendering of the patch dependency graph
pmerge         - merge pending heads from dependencies into patch branches
pmessage       - print the patch message(s)
pnew           - start a new patch branch
pstatus        - print status of current (or given) patch branch
reapply        - reverts the working copy of all files touched by REV to REV</pre>
</div>
<p>TortoiseHg will provide a new task tab that shows the patch dependency graph.</p>
<blockquote>
<div><div class="figure">
<img alt="Pbranch task tab" src="_images/pbranch.png" />
<p class="caption">Pbranch task tab</p>
</div>
</div></blockquote>
<p><strong>Installation</strong></p>
<p>As this extension is not installed with TortoiseHg, you have to download
it from <a class="reference external" href="http://bitbucket.org/parren/hg-pbranch">http://bitbucket.org/parren/hg-pbranch</a>. Be sure to dowload the
right one according to the Mercurial version included with TortoiseHg (see the
wiki page on the download site).
To test the use of this plugin, you can specify it on the Mercurial
command line like this:</p>
<div class="highlight-python"><pre>hg --config "extensions.pbranch=C:\path\to\pbranch.py" pstatus</pre>
</div>
<p>You may want to add it to your Mercurial.ini or a repository&#8217;s hgrc like this:</p>
<div class="highlight-python"><pre>[extensions]
pbranch = C:\path\to\pbranch.py</pre>
</div>
<p>If you do this, you can omit the &#8211;config command-line option.</p>
</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar">
        <div class="sphinxsidebarwrapper">
            <p class="logo"><a href="index.html">
              <img class="logo" src="_static/thg_logo_92x50.png" alt="Logo"/>
            </a></p>
  <h3><a href="index.html">Table Of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="#">8. Extensions</a><ul>
<li><a class="reference internal" href="#hgfold">8.1. Hgfold</a></li>
<li><a class="reference internal" href="#perfarce">8.2. Perfarce</a></li>
<li><a class="reference internal" href="#mercurial-keyring">8.3. Mercurial-Keyring</a></li>
<li><a class="reference internal" href="#projrc">8.4. projrc</a></li>
<li><a class="reference internal" href="#pbranch">8.5. pbranch</a></li>
</ul>
</li>
</ul>

  <h4>Previous topic</h4>
  <p class="topless"><a href="patches.html"
                        title="previous chapter">7. Patches</a></p>
  <h4>Next topic</h4>
  <p class="topless"><a href="nonhg.html"
                        title="next chapter">9. Use with other VCS systems</a></p>
  <h3>This Page</h3>
  <ul class="this-page-menu">
    <li><a href="_sources/extensions.txt"
           rel="nofollow">Show Source</a></li>
  </ul>
<div id="searchbox" style="display: none">
  <h3>Quick search</h3>
    <form class="search" action="search.html" method="get">
      <input type="text" name="q" />
      <input type="submit" value="Go" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    <p class="searchtip" style="font-size: 90%">
    Enter search terms or a module, class or function name.
    </p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             >index</a></li>
        <li class="right" >
          <a href="py-modindex.html" title="Python Module Index"
             >modules</a> |</li>
        <li class="right" >
          <a href="nonhg.html" title="9. Use with other VCS systems"
             >next</a> |</li>
        <li class="right" >
          <a href="patches.html" title="7. Patches"
             >previous</a> |</li>
        <li><a href="index.html">TortoiseHg 2.4.0 documentation</a> &raquo;</li> 
      </ul>
    </div>
    <div class="footer">
        &copy; Copyright 2012, Steve Borho and others.
      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
    </div>
  </body>
</html>