{"id":1615,"date":"2013-04-02T00:00:00","date_gmt":"2013-04-02T00:00:00","guid":{"rendered":"https:\/\/test.simple-talk.com\/uncategorized\/beginning-distributed-version-control-with-mercurial\/"},"modified":"2021-05-17T18:36:07","modified_gmt":"2021-05-17T18:36:07","slug":"beginning-distributed-version-control-with-mercurial","status":"publish","type":"post","link":"https:\/\/www.red-gate.com\/simple-talk\/development\/dotnet-development\/beginning-distributed-version-control-with-mercurial\/","title":{"rendered":"Beginning Distributed Version Control with Mercurial"},"content":{"rendered":"
\n

If you have only lived in the tranquil world of client-server version source control systems, inhabited by such predictable beasts as SVN<\/a> and TFS<\/a>, your first encounter with a distributed version control system (DVCS) might prove frustrating and scary. While both client-server and distributed systems share many commands, icons and menus they work quite differently.<\/p>\n

This article introduces a few DVCS concepts using Mercurial<\/a>, a popular version control system, as an example.<\/p>\n

The Next Generation<\/h2>\n

Many experts consider today’s distributed version control systems, such as, GIT<\/a>, Mercurial or Veracity<\/a>, to be the latest generation of version control software. Their architecture goes beyond that of the previous generations’ client-server designs, and it isn’t surprising that they demand a different mindset to use them effectively.<\/p>\n

\n

Risky Business<\/strong> <\/p>\n

Labeling a vendor’s version control product as either distributed or client-server is a risky business. Many of them claim to support both architectures. For example, when Microsoft announced a DVC-Team Foundation Server (TFS) solution did that make TFS a client-server, distributed or a hybrid version control system?<\/p>\n<\/div>\n

Architecture<\/h3>\n

Version control exists in order to allow several users to edit the same set of text files with minimum pain. There are many ways to accomplish this. The more traditional Client-server version control solutions use file locking, whereas distributed version control solutions prefer repository change coordination as shown below.<\/p>\n

\"1776-5da1630d-c1b1-4b9a-ae31-8c613abe7fa\"<\/p>\n

\n

Distributed Means Distributed<\/strong> <\/p>\n

Our article presents a relatively modest “centralized distributed version control” layout. Distributed Version Control Systems in the Enterprise explores several more complex layouts. Despite the simplicity of our layout it may very well be one of the most common in today’s enterprise.<\/p>\n<\/div>\n

The first Version Control systems used File-locking within a centralized repository. This involves explicitly checking out a file, and then checking it in after you’ve finished editing it. Such an approach ensures that only one user can change a specific file, but it also means that other users cannot change it until you’ve checked it in. This has developed into an ‘optimistic’ model where the system attempts to merge the contents of any file that has been worked on by two different people at the same time.<\/p>\n

Distributed version control systems build on this idea. Users still check files in and out of a repository except that now the repository is local and unshared. This essentially eradicates any file locking issues. It also introduces a new challenge: Instead of checking in a file users now must synchronize their local repository with the central repository, as this graphic shows.<\/p>\n

\"1776-98479cbf-9ac6-41c0-ade8-51efeec6abb\"<\/p>\n

It’d be nice to just lock them both and overwrite the older one. However, not even Client-server Version Control systems do that nowadays. It defeats the reason for team-based version control. To help overcome this synchronization obstacle, distributed version control systems use the concepts of changesets and branches.<\/p>\n

DVC tools bundle up all changes, such as files and folders, into a changeset. The changeset<\/a> is then forwarded to the appropriate repository branch.<\/p>\n

\"1776-c3b0870d-8c0d-4fdf-b4a1-7199ca111f3\"<\/p>\n

To apply the changeset to its branch, you need one other piece of information. Where in the branch does the changeset belong? Distributed version control systems answer this question by remembering the identity of the changeset from which the new one started.<\/p>\n

\"1776-28bf50ff-25d2-4d0c-86bc-d62e4e0543f\"<\/p>\n

The changeset architecture serves another helpful function. It allows two repositories to efficiently synchronize with each other in most situations by only exchanging some changesets, thereby rather than having to copy an entire repository.<\/p>\n

\n

Technically speaking…<\/strong> <\/p>\n

Distributed version control systems manage changesets as a directed acyclic graph. Relating changesets in this fashion allows for adding a new one without altering the repository before the addition.<\/p>\n<\/div>\n

Distributed version control does not avoid one substantial pain point of the client-server variant. Files within a changeset that don’t match the central repository’s version have to be reconciled. Users still need to merge their files’ changes with the central repository’s files.<\/p>\n

Changing Mindset<\/h3>\n

Distributed repositories are very different to work with than server-managed files.<\/p>\n

To begin with, client-server source control tools such as Team Foundation Server (TFS) expect users to execute “get latest” when refreshing their local copies of files. Distributed tools, such as Mercurial, expect a “pull” command to obtain any changesets from the central server that their local repository does not possess.<\/p>\n

To commit changes to a local file, a user must first check it out from the client-server source control repository, and then check it in. Distributed tools involve a two-step process. First, users commit their changes to their local repository which creates a changeset. Second, they “push” this new changeset to the central repository.<\/p>\n

Distributed version control tools place another, subtler demand on users. Every changeset is bound to a specific antecedent changeset along a specific branch. Therefore, whenever a user initiates a change they must establish that point. In technical parlance, users must set the “rev”, “revision” or “tip” that they’re working.<\/p>\n

Basic Operations<\/h2>\n

Let’s start our review of basic operations with an existential crisis. Our imaginary software developer cannot get their local committed changes to the Mercurial central repository. We will work through how they discover and address the problem via Hg Workbench<\/a>.<\/p>\n

The scenario involves two developers, Client 1 and Client 2. Each of these developers sport their own repository, DemoClient1<\/strong> and DemoClient2<\/strong> which synchronize with the central repository DemoServer<\/strong>. Client 1’s inability to push their latest changes to DemoServer<\/strong> kicks off the crisis…<\/p>\n

\n

Note:<\/strong> Our basic operations chat begins where a tutorial covered later in this article ends. This backward approach is not accidental. The tutorial covers product and command line details readers may not find too interesting. Our current discussion focuses on basic distributed version control tool activities.<\/p>\n<\/div>\n

Push<\/h3>\n

Client 1 completed the process of updating File1.txt<\/strong> and committed the changes to the local repository DemoClient1<\/strong>. The tragedy begins with the launching of the Hg Workbench and clicking the push button (\"1776-81cb9c29-2e28-4d7d-bd5a-1e846c5dc28\"). The central repository’s harsh, pink highlighted response informs Client 1 that the request cannot be executed and is therefore aborted. It informs the user why; the two repositories, DemoCleint1<\/strong> and DemoServer<\/strong>, are not synchronized. The pink window also suggests two fixes.<\/p>\n

\"1776-4a519704-63f7-46fa-934e-dc812ba0773\"<\/p>\n

The pink window recommends that Client 1 either “pull and merge” or “push -f to force” in order the get the gray highlighted Rev 1, “Client 1 updated Test File 1” changeset into DemoServer<\/strong>. Since anyone would be right to regard the notion of forcing change as being scary Client 1 elects the first recommendation.<\/p>\n

Before pulling anything, it helps to visualize the likely explanation for the cause of the Version Control system aborting Client 1’s “push”. Using our earlier branch-changeset graphic, you can guess that that another changeset node has jumped into the DemoServer<\/strong>‘s default branch before Client 1’s Rev 1 arrived.<\/p>\n

\"1776-47ef6bf9-3ce8-4243-ba09-e59803f8d0a\"<\/p>\n

Pull<\/h3>\n

Clicking the pull button, \"1776-6a6bf99c-1899-4467-b1eb-2590b070f59\", updates the Workbench’s ‘Revision Graph Details’ window as shown.<\/p>\n

\"1776-52265f78-ceed-453f-8e7c-a5e3600c144\"<\/p>\n

Our node diagram confirms our suspicions. Client 2 pushed changesets Rev 2 and Rev 3 into the central repository leaving our Rev 1 changeset adrift of it in the antecedent node. Client 1 needs to merge Rev 1 with the latest collection of changesets.<\/p>\n

\n

Note:<\/strong> The automatic splitting of the default branch into two branches as depicted by the Revision Graph Details windows confuses some first-time DVCS users. This confusion applies especially to developers reared on a client-server tool where branching had the pariah status of development option of last resort.<\/p>\n<\/div>\n

Merge<\/h3>\n

Merging begins with Client 1 switching their context to the latest changeset node. In Mercurial parlance, Client 1 “updates” their local version of source-controlled files to those of DemoServer<\/strong> by right-clicking the blue dot of Rev 3. Workbench reflects Client 1’s decision by changing the tip or “Rev” to the highlighted changeset as shown below.<\/p>\n

\"1776-a5d93690-dbda-4566-83ce-c1024739076\"<\/p>\n

Mercurial’s merge process begins with Client 1 right-clicking the Rev 1 changeset and executing the “Merge with local…”<\/em> menu item. This kicks off a wizard-like exercise walking Client 1 through a series of steps which includes resolving any file differences. If Client 1 successfully works through these steps, then the Revision Graph Details window as shown below displays a new changeset that captures these implicit merge edits.<\/p>\n

\"1776-52627369-9b7b-44f2-b1d9-0541e13f827\"<\/p>\n

\n

Merging Still Matters<\/strong> <\/p>\n

Some enterprises adopt a distributed version control solution in the belief that it simplifies the process of merging different source code branches. The changeset-node architecture along with the state of the art merging algorithms found in most DVC tools surely ease the worst of merge madness. But figuring out what stays and what goes when two files must become one remains a headache.<\/p>\n<\/div>\n

With both the local and server repositories synchronized, Client 1 is then ready to “push” once more, except this time with two changesets, the original Rev 1 and the merge Rev 4. Assuming Client 2 did not change something since the last “pull”, the “push” command succeeds as shown below in Client’s Workbench.<\/p>\n

\"1776-a780b659-4e88-4590-87ac-32b793f43e3\"<\/p>\n

Client 1’s crisis has ended. The central repository, DemoServer<\/strong>, now includes the Rev 1 changeset which initiated the crisis. Workbench confirms the fact with the green window’s text along with the “Phase” grid column of the two changesets. Before the push, the changesets’ exhibited a “draft” phase. Afterwards the phase they became “public” and available to any repositories working with DemoServer<\/strong>.<\/p>\n

Rebase<\/h3>\n

Some users find this merge process cumbersome if not graphically unappealing. <\/em>Why bother creating a second merge changeset and a short-lived branch just because another changeset jumped in? Couldn’t Client 1 simply update the DemoClient1<\/strong> repository and reapply the Rev 1 changeset? The short answer is yes; the supporting magic goes by the name “Rebase”.<\/p>\n

The decision to rebase occurs temporally and graphically at the same point as the “Merge with local…” option joined the fray as shown below.<\/p>\n

\"1776-598812a2-3212-46ee-8bec-4149b2d7a27\"<\/p>\n

As with the “Merge with local…” menu, “Rebase…” initiates a wizard-like workflow that helps the user to resolve any file differences. The difference is that, this time, when the wizard finishes, the Workbench displays a cleaner Revision Graph Details<\/em> window.<\/p>\n

\"1776-4e4d1fa2-1563-4190-af0f-f34213aa847\"<\/p>\n

Our simpler node graph happens after the rebase process tricks the local repository into believing that Client 1’s original changeset began with the central repository’s latest changeset, Rev 2. It does so by helping Client 1 to synchronize repositories and then quietly recreate the original changeset with the appropriate antecedent. You’d be able to confirm the story by carefully comparing the graphs that followed clicking “Merge with local…”<\/em> versus “Rebase…”<\/em> menus. (Hint: Look at the Rev 1 changeset.)<\/p>\n

By pushing the rebase changeset to DemoServer<\/strong>, we leave Client 1 emotionally uncompromised as well as artistically uncluttered: as show below.<\/p>\n

\"1776-a980cc8f-022d-428f-9685-59946603494\"<\/p>\n

\n

Merge or Rebase?<\/strong> <\/p>\n

Developers often ask whether it is better to merge or rebase. Ignoring artistic biases for linear or bumpy changeset graphs and complex technical minutiae, experience suggests a simple rule. If possible, rebase draft changesets; always merge public. Put another way, once a changeset hits the central server do not rebase – it’ll likely confuse other developers.<\/p>\n<\/div>\n

Tutorial Time<\/h2>\n

Rather than letting you struggle to learn distributed version control basics with a production repository, I’ll describe in this section the process of setting up and playing with Mercurial on a Windows computer. Our discussion covers several of the more ubiquitous ideas and line commands.<\/p>\n

Installation<\/h3>\n

Readers expecting pain when installing a server product on their computer will be disappointed. Installing and running Mercurial borders on fun. Start the exercise by downloading<\/a> the appropriate OS version.<\/p>\n

\n

Note:<\/strong> The discussion that follows used the “Mercurial 2.5.1 MSI installer – x86 Windows” install.<\/p>\n<\/div>\n

After downloading the installation executable, unblock<\/a> and click it. You are unlikely to endanger life by choosing any of the various installation options or defaults. The defaults should be fine for most requirements. Now run Mercurial via the command window.<\/p>\n

Initialization<\/h3>\n

Here are the commands used to create a local “server” repository and a local “client” repository.<\/p>\n

Starting from the root, which for this discussion will be C:\\, we will create the required directories and repositories. All of the commands are either DOS, in upper case, or Mercury, in lower case. All Mercury commands begin with the hg prefix. (Why “hg”? It’s the periodical table<\/a> identifier for the Mercury element.)<\/p>\n

MD HgDemo\r\nhg init c:\\HGDemo\\DemoServer\r\nhg init c:\\HGDemo\\DemoClient1<\/pre>\n
The init command creates directories and files for the “DemoServer<\/strong>” and “DemoClient1<\/strong>” repositories. Before going we need to attend to some further minor configuration information.<\/p>\n
First, visit the C:\\HgDemo\\DemoServer\\.hg<\/strong>directory. Once there create the file hgrc<\/strong> (no extension!) with your text editor and paste in these lines.<\/p>\n
[web]\r\npush_ssl=False\r\nallow_push=*<\/pre>\n
The two settings, push_ssl<\/strong> and allow_push<\/strong> enable our DemoServer<\/strong> repository to behave as a centralized repository.<\/p>\n
\n
Warning:<\/strong> The above [web] settings are unsuitable for production, but they are perfect for experimenting locally with Mercurial. For example, push ssl=False allows any user to push and pull changes to DemoServer<\/strong> without permission.<\/p>\n<\/div>\n
Next, visit the C:\\HgDemo\\DemoClient1\\.hg<\/strong> directory. There, create another hgrc file and paste in the below.<\/p>\n
[paths]\r\ndefault = http:\/\/localhost:8000\/\r\n[ui]\r\nusername = Client 1 <client1@test.com>\r\n[extensions]\r\nrebase =\r\nmq =<\/pre>\n
The first setting, default,<\/strong> links Client 1’s repository to DemoServer<\/strong>. The obvious username property gives DemoClient1<\/strong> a default user when working other repositories. The last two settings expose DemoClient1<\/strong> users to the rebase<\/a> functionality as discussed earlier in this article.<\/p>\n
\"1776-e4f401b7-c0b3-43aa-8d17-6a262119846\"<\/p>\n
With this file structure in place the repository can now be started with this serve <\/strong>command.<\/p>\n
CD c:\\HGDemo\\DemoServer\r\nhg serve\r\n<\/pre>\n
If we have configured everything properly, then http:\/\/localhost:8000\/<\/code> displays an empty DemoServer<\/strong> repository. Closing the command window or pressing CONTROL+C within will stop the server.<\/p>\n
\"1776-f7d472fa-1973-434c-8c7f-c3b26da8fc9\"<\/p>\n
Now that our initialization efforts are wrapped up, it is time to put the DemoServer<\/strong> repository to work.<\/p>\n
Working with DemoClient1<\/h3>\n
Client 1’s work begins with a new command window. Inside of it we will add TestFile1.txt<\/strong>; commit it to the DemoClient1<\/strong> repository; and push it to the DemoServer<\/strong> repository.<\/p>\n
CD C:\\HgDemo\\DemoClient1\\\r\nECHO COMMIT00 > TestFile1.txt\r\nhg add\r\nhg commit -m \"Client 1 added Test File 1\"\r\nhg push<\/pre>\n
The hg command, add, notifies the DemoClient1<\/strong> repository of the new TestFile1<\/strong> file. Client1<\/strong> can then commit it to the DemoClient1<\/strong> via hg commit<\/strong>. The -m<\/strong> parameter prefaces the required comment when committing a change. The last hg command, push<\/strong>, forwards the changeset to the DemoServer<\/strong> repository.<\/p>\n
Working with DemoClient2<\/h3>\n
With a populated central repository, Client 2 joins the fray by copying the DemoServer<\/strong> repository. Whereas Client 1 manually performed this task by configuring the path to DemoServer<\/strong>, Client2 takes a quicker and more typical route via the clone command within a new command window.<\/p>\n
MD C:\\HgDemo\\DemoClient2\\\r\nCD C:\\HgDemo\\DemoClient2\\\r\nhg clone http:\/\/localhost:8000\/<\/pre>\n
The hg clone command performs two tasks. First, it automatically populates the C:\\HgDemo\\DemoClient2\\<\/strong> directory with TestFile1.txt <\/strong>file. Second, it creates the C:\\HgDemo\\DemoClient2\\.hg\\hgrc<\/strong> file with the text “[paths] default = http:\/\/localhost:8000\/”.<\/p>\n
Before performing any work though, Client 2’s DemoClient2<\/strong> repository needs a little more configuration information akin to that of D<\/strong>emoCient1<\/strong>. Open C:\\HgDemo\\DemoClient2\\.hg\\hgrc and add the below after the existing [paths] default = http:\/\/localhost:8000\/<\/em> text.<\/p>\n
[ui]\r\nusername = Client 2 <client2@test.com>\r\n[extensions]\r\nrebase =\r\nmq =<\/pre>\n
With DemoCient2 <\/strong>configured, Client 2 may now work with their local repository and DemoServer<\/strong>. The next four commands add the file, TestFile2.txt<\/strong>, with the text “Committ01” and push it to the central repository.<\/p>\n
ECHO COMMIT01 > TestFile2.txt\r\nhg add\r\nhg commit -m \"Client 2 added Test File 2\"\r\nhg push<\/pre>\n
Client 2 is a busy developer and now updates the original TestFile1.txt <\/strong>with the below.<\/p>\n
ECHO COMMIT02 > TestFile1.txt\r\nhg commit -m \"Client 2 updated Test File 1\"\r\nhg push<\/pre>\n
Working (again) with DemoClient1<\/h3>\n
Client 1 was not slacking while Client 2 hammered away. Client 1 stayed busy editing and committing TestFile1.txt <\/strong>changes.<\/p>\n
CD C:\\HgDemo\\DemoClient1\\\r\nECHO COMMIT03 > TestFile1.txt\r\nhg commit -m \" Client 1 updated Test File 1\"\r\n<\/pre>\n
Some readers might wonder why the last command did not generate some kind of warning. How can both Client 1 and Client 2 alter and commit changes to TestFile1.txt<\/strong>? It turns out that Client 1’s repository does not know about Client 2’s edits which were committed to both DemoClient1<\/strong> and DemoServer<\/strong> repositories. As discussed in the earlier Basic Operations section of this article, Client 1 will need to resolve the different edits.<\/p>\n
Readers successfully completing this tutorial and visiting their local DemoServer<\/strong>‘s web site should see a page similar to that displayed below.<\/p>\n
\"1776-0dc2ebf9-5338-4ca0-bf78-4e33c39a362\"<\/p>\n
Conclusion<\/h2>\n
Our introduction ends with three points. First, we only skimmed the surface of distributed version control systems with Mercurial. Readers wishing to dive further may find Learn Mercurial<\/a> worth exploring. Second, many Mercurial users don’t find all the built-in tools productive. For example, they might catch a lift with PowerShell scripts like Posh-Hg<\/a>. Lastly, personal thanks to my friends at Thomson Reuters. Still amazes me that Barnabas H, Chad A, Rob G and Troy D never stopped providing intelligent answers to my many dumb questions. Thank you.<\/p>\n<\/div>\n","protected":false},"excerpt":{"rendered":"
The move from client-server version ontrol systems (VCS) to distributed version control systems can be bewildering.  Tom uses his experience of moving to Mercurial to explain those aspects of the move that are liable to cause confusion to anyone steeped in the culture of the traditional VCS. Rebase, Push, Pull and Merge explained!…<\/p>\n","protected":false},"author":200451,"featured_media":0,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[143538],"tags":[4143,4229,4156,5838,5716,5717,4179,5501],"coauthors":[17935],"class_list":["post-1615","post","type-post","status-publish","format-standard","hentry","category-dotnet-development","tag-net","tag-net-framework","tag-asp","tag-dvcs","tag-hg","tag-mercurial","tag-source-control","tag-version-control"],"acf":[],"_links":{"self":[{"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/posts\/1615","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/users\/200451"}],"replies":[{"embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/comments?post=1615"}],"version-history":[{"count":6,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/posts\/1615\/revisions"}],"predecessor-version":[{"id":78586,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/posts\/1615\/revisions\/78586"}],"wp:attachment":[{"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/media?parent=1615"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/categories?post=1615"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/tags?post=1615"},{"taxonomy":"author","embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/coauthors?post=1615"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}