Mercurial is one of those source control management systems that a token few people like and the vast majority of the world shuns. Most of us shun it for good reason. Git, on the other hand, is one of those source control management systems than many people like, and it is for no good reason.
Git is not a good SCM, it’s a wild wild west SCM. To use it for a medical device project (and pass audit) you have to have it so locked down the only way to utilize it is via GitKraken or some other GUI front end. People hate Perforce products because they aren’t the wild wild west of SCM. When you work in the medical device world you will find Perforce products everywhere.
No, this is not the first time I’ve written about Mercurial on this blog. There have been other “instructive” posts.
The Marketing
Hopefully you will all live long enough to learn this truth about marketing.
If something actually is easy and intuitive you don’t have to put it in your marketing literature. I’ve worked in advertising, this is a stupidity hook. Apple and Microsoft use stupidity hooks all of the time.
Branches by Any Other Name
I don’t care what you are working on, there will come a time when you need to reset way back to a prior known working version. The wild wild west of Git tends to fork into a separate repository and then have you issue a pull request. At the point in time you do this you have failed your FDA audit. You took code outside of primary source control into some other unregulated source control. When the auditors get done with you don’t plan on being able to sit down for days.
Mercurial has branches and revisions and many other things. What it doesn’t like is multiple heads. It also gets very difficult to tell what is actually in the HEAD based on the visual tools. Most other SCM products allow you to cleanly branch/fork/whatever within the primary SCM from a long ago point in time. Even the text based utilities will show you a proper revision tree.
The Situation
My fork of Scintilla to support CopperSpice had hummed along nicely with the older version of Scintilla. In fact, a project unrelated to mine, named NotepadNext which used Qt and Scintilla had also hummed along nicely using basically the same version of Scintilla. Big dummy me decided to update to the latest version of Scintilla because a new release of RedDiamond was close to finished.
The longest distance between any two points is a shortcut. The largest disasters in software are caused by an upgrade.
Roland Hughes
That’s a mantra to live by boys and girls. Before I merged in the code the print preview functionality worked like this.
After the upgrade.
If your color scheme/theme used a white background by default you would not see this.
I’m not dissing Neil or the Scintilla project. Shit like this happens in an AGILE world. He’s done a phenom job creating the Scintilla editor module and it is the core of many editors both free and commercial.
I am dumping on Mercurial and it’s “intuitive” nature. This was one big merge as I was several full releases behind. I had also done other coding before this particular oopsie got noticed. Getting back to good is not a Mercurial strong suit.
Getting Back to Good
You know me, I came up via computer operations so I made a safety copy of the entire directory tree on a different disk drive. Then I tried every documented method of “getting back to a very old rev” and none of them worked. Mercurial kept complaining about multiple heads and other things. You see via the image labeled “SourceForge Commit History” that I needed to get back to rev 065115. Once I verified that was good, check it in, then start applying the history of changes one by one. Once you do something like
hg revert -a -C -r 065115
hg branch print-issue
hg addremove
hg commit
hg push --new-branchThat’s it, you are screwed.
Am I going to spend 3+ days reading through Mercurial documentation to become one with the Mercurial “flows” to understand this? No. Neither are you! This is a common (*&^)(*&ing problem and the solution ought to be straight forward. If the syntax is “expert friendly” you should have a GUI. This not liking multiple heads leads Mercurial to get really discombobulated.
That’s right, Mercurial put my change at the tip and the tree GUI makes you believe my header/footer changes and all the stuff below are merged in safe and sound. Nope! Most definitely not in the local code. I’m back at 065115 with one more check-in to take out the compiler warning about no default on switch statements.
Searching for Tools
One of the more humiliating kicks to the crotch with Mercurial is that every tool you want to use appears to be DEPRECATED. Fine. Then give us something that actually works! Don’t just pull a Republican “Defund ObamaCare” without actually having something to replace it with. Today we still have ObamaCare and the Open Enrollment period is going on right now. Today we still have the DEPRECATED tools and that is what everyone is using.
hg view
The first deprecated tool you need is also one of the most useful, hg view. It is installed by default but not activated because they don’t want to add tk toolkit as a dependency. Your first step is to install tk 8.5 or higher.
Then you have to do some work in a terminal
Even though the extension is packaged with the hg command line tool, the tool doesn’t really know where it put the thing. While you are at it, find the histedit package as well.
cd
jed .hgrcYou need to uncomment the lines and add full path to the packages to “enable” them for the hg command line. If you don’t have jed use nano or your other favorite terminal editor. After editing your file should look like this.
# example user config (see 'hg help config' for more info)
[ui]
# name and email, e.g.
# username = Jane Doe <jdoe@example.com>
username = roland_hughes
# We recommend enabling tweakdefaults to get slight improvements to
# the UI over time. Make sure to set HGPLAIN in the environment when
# writing scripts!
# tweakdefaults = True
# uncomment to disable color in command output
# (see 'hg help color' for details)
# color = never
# uncomment to disable command output pagination
# (see 'hg help pager' for details)
# paginate = never
[extensions]
# uncomment the lines below to enable some popular extensions
# (see 'hg help extensions' for more info)
#
histedit = /usr/lib/python2.7/dist-packages/hgext/histedit.py
# rebase =
# uncommit =
hgk = /usr/lib/python2.7/dist-packages/hgext/hgk.py
After that (possibly needing to log out/in) you should be able to type
cd ~/sf_projects/csscintilla-csscintilla
hg viewYou need to cd to the root of your repo clone so view knows what to view.
This tool has much the same misleading information in the tree
It has one, possibly unique, feature that is “expert friendly.”
Right click on a revision that’s not in your tree, no matter what Mercurial believes, gives you a menu where you can “write commit to file.” You will note it creates a .diff file and writes it to the root of your project directory.
We still have ObamaCare because, despite all its warts and short-comings, it works. We still have this DEPRECATED tool because, once somebody shows you the expert friendly tricks, you can dig yourself out of a very deep hole. One by one you write the .diff files and import them.
TortoiseHg
TortoiseHg gets dumped on and deservedly so. On Ubuntu it is distributed via the Snap store. It isn’t properly packaged. You don’t get a nice desktop entry in “Activities” and if you try to launch it from a non-repo directory File-Open won’t let you open the file you need. This is due to Snap’s “portals.” Snap packaged tools don’t get to have their own file browser. Apparently they cannot communicate with the portal file browser well enough to tell it what to stop on. When you navigate to the “.hg” file in your repo directory and click “open” the file browser goes into the directory rather than returning the path to the .hg file.
You have to be in a terminal, cd to your repo root directory then type thg. You will then be greeted by lots of ugly messages and finally a GUI.
Note that SourceForge has completely different revision numbers than either hg view or TortoiseHg. At least these two programs show the same numbers. When you are working from the command line using -r the revision number needs to match what SourceForge has.
Careful viewers will note I opened TortoiseHg after I imported the commit diff file. The display looks nicer and it is a bit easier to identify what you want. You can right click on an entry and navigate the menu to create a patch file.
Given the “Diff” menu entries above “Patch” might be confusing. Here again you get burned by the Snap packaging. A “portal” window opens and you may not see it at all. When I did this it opened behind everything else on the screen. I had to scroll the Ubuntu “favorites and active” menu on the left down quite a bit to find a gear icon I didn’t recognize. The other thing that burns you is it doesn’t default the name. Hg view uses commit-somenumber.diff. The number matches the rev. This is a logical file name. When users are required to come up with names you will find they are all a.diff. I chose abc.diff just to be different.
Patch vs. Diff
You will notice our first .diff looks much the same as the second despite the term “patch.”
Applying the diff is interesting.
The TortoiseHg window immediately jumps to the revision we just imported. If you scroll back to the top though
It live updates the description so you can keep track of what you last imported.
Summary
If you need to go way back to see where something went wrong Mercurial has a convoluted way to go about it. You really need to have both hg view and TortoiseHg due to the most unfortunate packaging choice of TortoiseHg. Had TotoiseHg been packaged for native install it would be the one tool you needed after you learned the expert friendly method of creating a branch from an old rev.
One thing that is missing is the GitKraken “Branch Here” capability. Maybe it exists, but it isn’t obvious. Another thing of note is that after I closed the one development branch, hg view would no longer show me the revision I needed to start with. Both SourceForge and tortoiseHg show it to me, they just use different revision numbers. This is why so many medical device companies buy a Perforce product, no matter how you access the repo, you get the same interface with the same revision information.
