Source

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

  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
433
434
435
436
437
438
439
440
441
442
443
444


<!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>4. A Quick Start Guide to TortoiseHg &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="5. TortoiseHg in daily use" href="daily.html" />
    <link rel="prev" title="3. What’s New" href="whatsnew.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="daily.html" title="5. TortoiseHg in daily use"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="whatsnew.html" title="3. What’s New"
             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-tour">
<span id="a-quick-start-guide-to-tortoisehg"></span><h1>4. A Quick Start Guide to TortoiseHg<a class="headerlink" href="#module-tour" title="Permalink to this headline"></a></h1>
<p>Welcome to TortoiseHg and the Mercurial!  TortoiseHg is a set of graphical
applications and Windows Explorer shell extension that serve as a friendly
front-end to the Mercurial distributed version control system (DVCS).</p>
<p>All TortoiseHg functionality is reachable from 3 places:</p>
<ol class="arabic">
<li><p class="first">The <strong class="command">Workbench</strong> application</p>
<blockquote>
<div><p>You can start the Workbench from the Start Menu, or by right clicking on the
Desktop and selecting <em class="menuselection">Hg Workbench</em>.</p>
<div class="figure">
<img alt="Desktop Context Menu" src="_images/desktop-workbench.png" />
</div>
<p>Start the Workbench from the Desktop</p>
</div></blockquote>
</li>
<li><p class="first">The <strong class="command">Explorer</strong> context menu</p>
<blockquote>
<div><p>All you have to do is right click on the right folder or files in Explorer,
and select a context menu entry.</p>
</div></blockquote>
</li>
<li><p class="first">The <strong class="command">thg</strong> command line application</p>
<blockquote>
<div><p>Type the appropriate commands from any command line interface, in the form
<tt class="kbd docutils literal"><span class="pre">thg</span> <span class="pre">&lt;command&gt;</span> <span class="pre">[options]</span></tt>.</p>
</div></blockquote>
</li>
</ol>
<p>In this quick guide we would like to make you get started using the Workbench
application, but we will also indicate how to do the same with the other
possibilities.</p>
<p>Mercurial commands are also available from the standard <strong class="command">hg</strong> command
line application.</p>
<div class="section" id="configuring-tortoisehg">
<h2>4.1. Configuring TortoiseHg<a class="headerlink" href="#configuring-tortoisehg" title="Permalink to this headline"></a></h2>
<p>Your first step should be to make sure that you are correctly identified
to TortoiseHg.  You do this by opening the global settings dialog.</p>
<p>Workbench: select <em class="menuselection">File ‣ Settings...</em> from the menu</p>
<p>Explorer: choose <em class="menuselection">TortoiseHg ‣ Global Settings</em> from the
context menu</p>
<p>Command line: type <strong class="command">thg userconfig</strong></p>
<p>This opens the TortoiseHg settings dialog, editing your global
(user) configuration.</p>
<div class="figure">
<img alt="Settings Dialog" src="_images/settings.png" />
<p class="caption">TortoiseHg Settings Dialog</p>
</div>
<p>First select the <em class="guilabel">Commit</em> page and enter a name in the
<em class="guilabel">Username</em> field.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">If you neglect to configure a username TortoiseHg will ask you to
enter one when you try to <em>commit</em>, which is the first time a
username is actually required.</p>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>There are no hard fast rules on how to format your username, the
field is free form, but the following convention is commonly used:</p>
<div class="highlight-python"><pre>FullName &lt;email&gt;</pre>
</div>
<p>for example</p>
<div class="highlight-python"><pre>Donald Duck &lt;donaldduck@example.net&gt;</pre>
</div>
<p class="last">The email address is stripped when viewing history in the revision history
viewer, and the built-in web server obfuscates email addresses to
prevent SPAM.</p>
</div>
<p>Next, select the <em class="guilabel">TortoiseHg</em> page and select the
<em class="guilabel">Three-way Merge Tool</em> entry.  In the drop down list you will
find all of the merge tools detected on your computer (kdiff3 is
provided by the Windows installer) and a number of internal merge
behaviors.  Select your preferred merge tool.</p>
<p>If you prefer for TortoiseHg to also use your selected merge tool for
visual diffs, you can leave the <em class="guilabel">Visual Diff Tool</em>
unspecified.  Otherwise, select your favorite visual diff tool from the
drop down list of detected visual diff tools.</p>
<p>If there are no options in either drop-down list, you must install a
diff/merge tool that is supported by our mergetools.rc or configure your
own tool.</p>
<p>Feel free to configure other global settings while you have the dialog
open.  You will have the chance later to override these global settings
with repository local settings, if required.</p>
<p>Click the <em class="guilabel">OK</em> button to save the changes you have made and
close the settings dialog.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Most TortoiseHg settings changes are noticed immediately, but
loading or unloading extensions usually requires restarting all open
applications for the changes to take effect.</p>
</div>
</div>
<div class="section" id="getting-acquainted">
<h2>4.2. Getting Acquainted<a class="headerlink" href="#getting-acquainted" title="Permalink to this headline"></a></h2>
<p>Mercurial supports many different
<a class="reference external" href="https://tortoisehg.bitbucket.org/hgbook/1.7/collaborating-with-other-people.html">collaboration models</a>.
This chapter describes just one of those models: a single central repository.
The central repository model does not scale as well as other models, but
it is the most familiar to those coming from other revision tools and
thus is the most common approach people start with.</p>
<p>To get started, suppose you volunteer to create the central repository.
There are ways to <a class="reference external" href="http://mercurial.selenic.com/wiki/RepositoryConversion">convert</a>
non-Mercurial repositories into Mercurial repositories, but this example
assumes you are starting from scratch.</p>
</div>
<div class="section" id="initialize-the-repository">
<h2>4.3. Initialize the repository<a class="headerlink" href="#initialize-the-repository" title="Permalink to this headline"></a></h2>
<p>Create the initial repository on your local machine:</p>
<p>Workbench: select <em class="menuselection">File ‣ New Repository...</em> from the menu</p>
<p>Explorer: select <em class="menuselection">TortoiseHg ‣ Create Repository Here</em> from
the context menu</p>
<p>Command line: type <strong class="command">thg init</strong></p>
<p>You can do this from within the folder you want to create the repository in, or
enter the correct path in the dialog. You only need to do this once in the root
folder of your project.</p>
<div class="figure">
<img alt="Init dialog" src="_images/init.png" />
<p class="caption">Repository Init Dialog</p>
</div>
<p>We suggest you keep <em class="guilabel">Add special files (.hgignore, ...)</em>
checked, and do not check <em class="guilabel">Make repo compatible with Mercurial &lt; 1.7</em>,
unless you have a strong reason to do so.</p>
<p>After pressing <em class="guilabel">Create</em>, Mercurial creates a subdirectory in
your project folder named <tt class="file docutils literal"><span class="pre">.hg</span></tt>.  This is where Mercurial keeps all
its version data.  It is called the <em>repository</em> or <em>store</em>, while the
directory containing the source files is called the <em>working directory</em>.
You never need to specify the <tt class="file docutils literal"><span class="pre">.hg</span></tt> directory when running
commands, you only need to specify the working directory root.  It is
mentioned here just so you better understand how Mercurial works.</p>
<p>The new repository will also be added to the RepoRegistry when you perform this
operation from the Workbench.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">It is dangerous to manually edit the files in <tt class="file docutils literal"><span class="pre">.hg</span></tt> directory,
repository corruption can occur.  <tt class="file docutils literal"><span class="pre">.hg/hgrc</span></tt> is perhaps the
only exception to this rule.</p>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Perhaps you already created one or more repositories.  As you can manage
multiple repositories in the Workbench at the same time, you can add these
existing repositories by selecting <em class="menuselection">File ‣ Open Repository...</em>
from its menu, and selecting their folder.  Or you could drag their folder
from Explorer into the RepoRegistry pane.</p>
</div>
</div>
<div class="section" id="add-files">
<h2>4.4. Add files<a class="headerlink" href="#add-files" title="Permalink to this headline"></a></h2>
<p>Now it&#8217;s time to tell Mercurial which files must be tracked. There are various
ways to do this:</p>
<ol class="arabic simple">
<li>Workbench: goto the Commit task tab, rightclick on the file, and select
<em class="menuselection">Add</em> from the context menu. This will change the status
indication of that file into &#8216;A&#8217; and the filename will turn green.</li>
<li>Explorer: select <em class="menuselection">TortoiseHg ‣ Add Files...</em> in the context
menu. A dialog will open for you to check the selected files and accept the
add operation. You can also open the status tool by selecting
<em class="menuselection">TortoiseHg ‣ View File Status</em>. Check the files you want
to add and select <em class="guilabel">Add</em> from the file context menu.</li>
<li>Command line: type <strong class="command">thg status</strong></li>
<li>Or skip adding new files as a separate step and have the commit tool add them
implicitly.  The commit tool is very similar to the status tool and allows
you to do all of the same tasks. In this tool you can add and commit an
untracked file by just checking the file and pressing <em class="guilabel">Commit</em>.</li>
</ol>
</div>
<div class="section" id="ignore-files">
<h2>4.5. Ignore files<a class="headerlink" href="#ignore-files" title="Permalink to this headline"></a></h2>
<p>You may have some files in the foldertree of your repository that you don&#8217;t want
to track. These can be intermediate results from builds f.i. that you do not
wish to always delete immediately, or files your editor generates, etc. You can
mark these files as ignored in some different ways too.</p>
<ol class="arabic simple">
<li>Workbench: goto the Commit task tab, rightclick on the file, and select
<em class="menuselection">Ignore...</em> from the context menu to open the ignore filter
dialog.</li>
<li>Explorer: select <em class="menuselection">TortoiseHg ‣ Edit Ignore Filter</em>.</li>
<li>Command line: type <strong class="command">thg hgignore</strong> to bring up the ignore filter dialog.</li>
<li>You can also launch the ignore filter from the status tool (the menu option
is named <em class="guilabel">Ignore</em>).</li>
</ol>
<p>Choose a file from the list or manually type in a <em>Glob</em> or <em>Regular expression</em>
filter and then press <em class="guilabel">Add</em>. Changes to the ignore filter take effect
immediately.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The <tt class="file docutils literal"><span class="pre">.hgignore</span></tt> file, contained in the working directory root,
is typically tracked (checked in).</p>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">It is good practice to not have many <em>unknown</em> files in your working
directory, as it makes it too easy to forget to add vital new files.
It is recommended that you keep your <tt class="file docutils literal"><span class="pre">.hgignore</span></tt> file up to
date.</p>
</div>
</div>
<div class="section" id="commit">
<h2>4.6. Commit<a class="headerlink" href="#commit" title="Permalink to this headline"></a></h2>
<p>Commit your local repository now:</p>
<p>Workbench: click on the Working Directory revision which also selects the Commit
task tab, or directly select the Commit task tab</p>
<p>Explorer: right-clicking anywhere in the folder, or on the folder itself, and
then selecting <em class="guilabel">Hg Commit...</em></p>
<p>Command line: type <strong class="command">thg commit</strong></p>
<p>Write a commit message, select the files you wish to commit, then press
<em class="guilabel">Commit</em>.  Your previous commit message will be in the message history
drop-down, so you do not have to type it in again from scratch.</p>
<div class="figure">
<img alt="Commit dialog" src="_images/commit.png" />
<p class="caption">Commit Tool</p>
</div>
</div>
<div class="section" id="share-the-repository">
<h2>4.7. Share the repository<a class="headerlink" href="#share-the-repository" title="Permalink to this headline"></a></h2>
<p>Now you are ready to share your work. You do this by making a copy of
your repository in a public location that everyone in your group can
read. Mercurial calls this copy operation <em>cloning your repository</em>.</p>
<p>To clone your repository to a shared drive:</p>
<p>Workbench: select <em class="menuselection">File ‣ Clone Repository...</em> from the menu</p>
<p>Explorer: select <em class="menuselection">TortoiseHg ‣ Clone...</em> from
the context menu</p>
<p>Command line: type <strong class="command">thg clone</strong></p>
<p>Then enter the destination path, and click <em class="guilabel">Clone</em>.</p>
<div class="figure">
<img alt="Clone dialog" src="_images/share.png" />
<p class="caption">Clone Dialog</p>
</div>
<p>When you create a clone for the purposes of generating a <em>central
repository</em> there is no reason for that clone to have a working
directory.  Checking <em class="guilabel">Do not update the new working directory</em> under
<em class="guilabel">Options</em> will prevent Mercurial from checking out a working copy of
the repository in the central repository clone.  It will only have the
<tt class="file docutils literal"><span class="pre">.hg</span></tt> directory, which stores the entire revision history of the project.</p>
<p>Other team members can clone from this clone with or without a checked
out working directory.</p>
</div>
<div class="section" id="fetching-from-the-group-repository">
<h2>4.8. Fetching from the group repository<a class="headerlink" href="#fetching-from-the-group-repository" title="Permalink to this headline"></a></h2>
<p>You want to start collaborating with your team.  They tell you something
like <em>fetch the repository from x</em>.  What does that mean? It means that
you want to make a copy of the repository located at x on your local machine.
Mercurial calls this cloning and TortoiseHg has a dialog for it.</p>
<p>Workbench: select <em class="menuselection">File ‣ Clone Repository...</em> from the menu</p>
<p>Explorer: select <em class="menuselection">TortoiseHg ‣ Clone...</em> from
the context menu</p>
<p>Command line: type <strong class="command">thg clone</strong></p>
<p>Then enter the destination path, and click <em class="guilabel">OK</em>.</p>
<div class="figure">
<img alt="Clone dialog" src="_images/clone.png" />
<p class="caption">Clone Dialog</p>
</div>
<p>This time you do want to update the working directory because you want
to work on the project, under <em class="guilabel">Options</em> uncheck
<em class="guilabel">Do not update the new working directory</em> so Mercurial updates
the working directory with the <em>tip</em> revision in your new clone.</p>
</div>
<div class="section" id="working-with-your-repository">
<h2>4.9. Working with your repository<a class="headerlink" href="#working-with-your-repository" title="Permalink to this headline"></a></h2>
<p>Suppose you&#8217;ve introduced some changes.  It is easy to discover what pending
changes there are in the repository.</p>
<p>Workbench: go to the Commit task tab and inspect the filelist at the left</p>
<p>Any files marked with &#8216;A&#8217; (added, green), with &#8216;?&#8217; (unversioned but not ignored,
fuchsia), with &#8216;M&#8217; (modified, blue), or with &#8216;!&#8217; (removed, red) indicate pending
changes that should be committed.</p>
<p>The Commit task tab in the Workbench gives you a way to see differences within
the files, or you can use your visual difference tool (kdiff3).  Mercurial
allows you to commit many changes before you decide to synchronize (share
changes) with the group repository.</p>
<p>Explorer: inspect the icons on the folders and files in your repository</p>
<p>Folders or files in Explorer marked with one of the icons below are another way of
indicating pending changes.  You can traverse the directories to find specific
changes and commit them from Explorer. Though it might be quicker to do that
from the Commit task tab in the Workbench.</p>
<div class="figure">
<img alt="Overlay Icons" src="_images/overlayicons.png" />
<p class="caption">Overlay Icons on Vista</p>
</div>
<p>Command line: type <strong class="command">thg commit</strong></p>
<p>When you&#8217;re ready to publish your changes, you</p>
<ol class="arabic simple">
<li>Commit your changes to your local repository (see above).</li>
<li>Pull changes from the group repository into your repository using
<em class="menuselection">TortoiseHg ‣ Workbench</em> or <strong class="command">thg log</strong>, select the
Sync task tab, choose the path to the group repository in the syncbar and
then click the <em class="guilabel">Pull</em> button.</li>
<li>If some changesets were pulled, merge those changes with your local
changes and then commit the merge into your local repository. From
the revision history viewer (<em class="menuselection">TortoiseHg ‣ Workbench</em>
or <strong class="command">thg log</strong>) open the context menu over the changeset
which you want to merge and select <em class="guilabel">Merge with local...</em>.
Finally, in the merge dialog, press <em class="guilabel">Merge</em> and then
<em class="guilabel">Commit</em>.</li>
<li>Ensure your merged work still builds and passes your extensive test suite.</li>
<li>Push your changes to the group repository,
<em class="menuselection">TortoiseHg ‣ Workbench</em> or <strong class="command">thg log</strong>,
select the path to group repository and then click the <em class="guilabel">Push</em>
button.</li>
</ol>
<p>Which may sound complicated, but is easier than it sounds.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Merges can be safely restarted if necessary.</p>
</div>
<p>Mercurial makes collaboration easy, fast, and productive.
Learn more at Mercurial&#8217;s <a class="reference external" href="http://mercurial.selenic.com/wiki/">wiki</a>.</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="#">4. A Quick Start Guide to TortoiseHg</a><ul>
<li><a class="reference internal" href="#configuring-tortoisehg">4.1. Configuring TortoiseHg</a></li>
<li><a class="reference internal" href="#getting-acquainted">4.2. Getting Acquainted</a></li>
<li><a class="reference internal" href="#initialize-the-repository">4.3. Initialize the repository</a></li>
<li><a class="reference internal" href="#add-files">4.4. Add files</a></li>
<li><a class="reference internal" href="#ignore-files">4.5. Ignore files</a></li>
<li><a class="reference internal" href="#commit">4.6. Commit</a></li>
<li><a class="reference internal" href="#share-the-repository">4.7. Share the repository</a></li>
<li><a class="reference internal" href="#fetching-from-the-group-repository">4.8. Fetching from the group repository</a></li>
<li><a class="reference internal" href="#working-with-your-repository">4.9. Working with your repository</a></li>
</ul>
</li>
</ul>

  <h4>Previous topic</h4>
  <p class="topless"><a href="whatsnew.html"
                        title="previous chapter">3. What&#8217;s New</a></p>
  <h4>Next topic</h4>
  <p class="topless"><a href="daily.html"
                        title="next chapter">5. TortoiseHg in daily use</a></p>
  <h3>This Page</h3>
  <ul class="this-page-menu">
    <li><a href="_sources/quick.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="daily.html" title="5. TortoiseHg in daily use"
             >next</a> |</li>
        <li class="right" >
          <a href="whatsnew.html" title="3. What’s New"
             >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>