<?php include('../HEADER.php'); ?>

<h1>Mercurial code management notes</h1>

<p><em>hg</em> is the chemical symbol of the element mercury.</p>

<h2>Basic workflow</h2>

<p>Starting a new repository:</p>

<code>cd myproj
hg init
hg add
hg status
hg commit -m 'Initial import.'</code>

<p>Reviewing changes after editing some files:</p>

<code>hg status
hg diff
hg commit -m 'Refactored widgets.'
hg tip -vp</code>

<p>Clone to a remote repository (note that Mercurial assumes path relative to home directory, so <code>~</code> in unnecessary; use <code>//</code> if you need an absolute path):</p>

<code>hg clone ./ ssh://example.com/projects/myproj</code>

<p>Update local repository from remote repository (and update working copy):</p>

<code>hg pull ssh://example.com/projects/myproj/
hg update</code>

<p>Push local changes to a remote repository:</p>

<code>hg status
hg commit -m 'Code cleanup.'
hg push ssh://example.com/projects/myproj/</code>

<p>See a history of changes with <code>hg log -r :</code> or <code>hg log -v</code>. Examine history of a particular changeset with <code>hg log -v -r 3</code> (where "3" is the start of a changeset id like "3:0272e0d5a517").</p>

<p>Change the working copy to a different revision like <code>hg update 3</code>, and change back to the latest revision with <code>hg update tip</code>.</p>

<p>To stop tracking a file under version control: <code>hg remove myfile</code>.</p>

<p>Also: <code>hg copy file1 file2</code> and <code>hg rename old new</code>.</p>

<p>See <a href="http://hgbook.red-bean.com/read/finding-and-fixing-mistakes.html">finding and fixing mistakes</a> for how to rollback the last commit (<code>hg rollback</code>), revert pre-commit changes (<code>hg revert file</code>), and more.</p>

<h2>Ignoring certain files</h2>

<p>If it doesn't already exist, create an <code>.hgignore</code> file in the root of the repository. if you run <code>hg status</code> and see:</p>

<pre>M myrepo/foo/doc.tex
? myrepo/foo/doc.aux
? myrepo/foo/doc.log</pre>

<p>Add the line <code>myrepo/foo/doc.log</code> to <code>.hgignore</code>, and Mercurial will ignore that file. It should no longer show when you run <code>hg status</code>. You can also add patterns to the ignore file, such as <code>.*.swp</code> to ignore vim's swap files.</p>

<h2>Initial setup</h2>

<p>After installing Mercurial, create an <code>~/.hgrc</code>:</p>

<code>[ui]
username = John Smith &lt;jsmith@example.com&gt;
editor = gvim
merge = meld

[merge-tools]
meld.args = $local $other $base
meld.priority = 1

[extensions]
hgext.extdiff =
hgext.hgk =

[extdiff]
cmd.meld =
cmd.vimdiff = gvim</code>

<p>Stick this in <code>myproject/.hg/hgrc</code>:</p>

<code>[paths]
default = ssh://example.com/repo/myproject</code>

<h2>Concepts and terminology</h2>

<p>Unlike SVN or CVS, Mercurial is a distributed system. Instead of having one central repository from which developers checkout individuals files, in a distributed system each developer clones the entire repository. This is practical because distributed systems are better at merging than SVN or CVS, and faster generally.</p>

<p>A Mercurial repository has a <strong>store</strong> (stored in the <code>.hg</code> directory) and a <strong>working copy</strong>. It is possible (and often useful) to checkout older version from the repository into the working copy.</p>

<p>Each commit generates a <strong>changeset</strong>, which records the state of the working directory. Each changeset has its own changeset ID.</p>

<p>A <strong>head</strong> is a changeset with not child changesets. A <strong>tip</strong> is the most recently changed head in a repository.</p>

<p>A <strong>branch</strong> is a repository, a repository is a branch. Each time you clone a repository, you create a new branch. (Technically, a branch is the set of all changesets with the same branch name. The default branch name is 'default', so a repository will be all once branch unless you create a named branch.)</p>

<p>A <strong>tag</strong> is a symbolic identifier for a changeset. A local tag (<code>hg tag -l my_tag</code>) is a convenience identifier that is not revision controlled, and doesn't propagate with other changes. A tag with no special specifier (<code>hg tag my_tag</code>) <em>is</em> revision controlled, and does propagate with other changes.</p>

<h2 id="links">Links</h2>

<ul>
	<li><a href="http://hgbook.red-bean.com/read/">Mercurial: The Definitive Guide</a></li>
	<li><a href="http://mercurial.selenic.com/wiki/UnderstandingMercurial">Understanding Mercurial</a></li>
	<li><a href="http://mercurial.selenic.com/wiki/CvsConcepts">Mercurial workflow (compared to CVS)</a></li>
    <li><a href="http://stevelosh.com/blog/2009/08/a-guide-to-branching-in-mercurial/">A Guide to Branching in Mercurial</a></li>
	<li><a href="http://mercurial.selenic.com/">Mercurial homepage</a></li>
	<li><a href="http://bitbucket.org/snej/murky/wiki/Home">Murky</a> OS X Mercurial client</li>
</li>


<?php include('../FOOTER.php'); ?>
