Here’s another advent blog series! This time it’s from Kamal Marhubi
and it’s on the subject of Mercurial. It’s pretty interesting, especially
for giving a fresh perspective on Mercurial’s user experience.

The introduction post lays down some of what makes Mercurial interesting
(phases, changeset evolution, extensibility) while the third post catches
up to another cool thing (revsets, one of my favourite Mercurial features) that
was missing from that initial list.

Extensions and papercuts

There’s a good article in the series about how Mercurial’s reliance on
extensions (and more specifically the need to explicitely enable them) is one of
the several “papercuts” you get when you start using it. This reminded me of
Josef Sipek’s “Modern Mercurial” blog series which starts with an
article precisely about that problem:

Then it suddenly hit me —- before these tweaks, I had been using Mercurial
like it’s still 2005!

I think this is a very important observation. Mercurial didn’t seem to be
improving because none of the user-visible changes were forced onto the users.

The problem is that the Mercurial devs have an extremely strict approach to how
the CLI should behave, and how no breaking changes should ever be introduced.
This means that:

1. No “dangerous” commands should be accessible by default ("don’t give the
   user opportunities to shoot their own foot"), which explains why history
   rewriting commands like rebase are disabled out-of-the-box.
2. Things that were later added (like colours, pager support, etc.) were often
   done in an optional extension to not break previous behaviour.

Arguably, these strict rules are partially the reason why the Mercurial CLI is
so nice to use compared to other CLIs like Git’s, but they’re also obviously
causing a lot of pain elsewhere.

I naively think this might be somewhat fixable by:

• Making the first hg run setup some sane default if it doesn’t find any user
  .hgrc (i.e. better bootstrapping).
• Relaxing some of the strict CLI rules by realizing that most use-cases that
  rely on specific historical behaviours (like automated scripts) are already
  most probably setting environment variables like HGPLAIN, in which case
  Mercurial can disable some of the more “human facing” features.

But of course, it’s lot more complicated than this… and to some degree, this
was addressed with the tweakdefaults setting (formerly known as “friendly
hg”), but, ironically enough, you still need to know about enabling
it, since it default to false, of course.

Staging areas

The fourth post talks about how Mercurial doesn’t have a staging area
(a.k.a. index) like in Git.

It’s kind of funny to me that we have people who started with Git as their first
(and sometimes only) VCS, and it will soon dawn on them that, frankly, there’s
nothing out there quite like Git’s index (well, at least not in any of the
half-dozen VCSes I’ve used so far). Git’s pretty unique on that front.

Although I don’t recommend trying to emulate a tool’s idiosyncratic workflow
when using another tool, people coming from Git invariably ask about this so
there’s always been some partial answer for Mercurial. A few years ago, the MQ
extension was that answer (it kinda gives you something that looks like
multiple staging areas!), but it seems that most of the Mercurial community
has moved away from it (I have too). MQ is still available for those who want
it, but these days it seems that using secret phases and history rewriting is
more common (and it also kinda gives you multiple staging areas too!).

I don’t really do that, but I imagine it would work along the lines of:

[alias]
newstage = commit -s -m "STAGING AREA"
upstage = commit --amend

So when you start working on something new, you push your work-in-progress with
hg newstage into a secret commit called “STAGING AREA”. Since it’s secret,
it won’t get pushed and will stay local. Then, as you keep working, you run hg upstage every now and then to “grow” that commit. When it’s ready, you change
that commit’s phase to draft. It’s a bit clunky (there are 2 aliases when
ideally there would be only one) but you get the idea, and with a bit of
scripting I’m sure that it’s possible to get it down to a similar UX as Git’s.

Twelve days to go

Anyway, we’re still half-way to Christmas so check out Kamal’s blog
for the rest of the series (assuming he keeps it going 🙂 ).

Advent blogging, i.e. blogging about a specific subject every day between December 1st and December 24th, seems to be picking up steam quite a bit this year. In the previous years, FastMail was pretty much the only one in my feeds doing this but, ironically, as they stopped doing it this year, it’s been replaced by others like Micro.blog’s Manton Reece (although he’s only doing half of it) or Vimways.

Inspired by 24ways, another advent blog dating back a dozen years, Vimways is, as you might guess, about Vim!

I was flattered to have Gutentags, my little Vim plugin, mentioned in the 2nd entry of the blog, even if the Daniel Moch, the author, said he stopped using it a while ago. Since the various methods mentioned in the article are not all equivalent, I figured I would add some clarifications here.

This requires some basic knowledge about Vim’s tags feature-set, but thankfully if you’ve read the aforementioned Vimways article, you should know everything you need to.

Synchronization and scalability

Tags files contain the symbols of your codebase. As you work, however, symbols change – you add and remove methods, rename them, change their signature, etc. So, unless something is being done about it, the tags files slowly but surely get out-of-sync with the source code, until you can’t really jump around anymore (it’s common for me to keep a Vim instance alive for days on end!). Having something that can keep the tags in sync with code as you work on the latter is therefore important.

Now, most “simple” methods for managing tags files rely on running ctags whenever the tags file needs to be kept in sync with the source code. This works fine for most cases, because the codebase is either small (like in most utility/low-level libraries) or large but broken up in small pieces whose vast majority is excluded from the tags files (like most web development projects where all dependencies are in a node_modules-type folder).

For bigger codebases, however, this quickly breaks down because ctags takes a long time to run. It’s more efficient to only update the part of the tags file that relates to the code you’re changing, and leave the rest alone.

Gutentags does this by running ctags only on the file you just saved in Vim.

If you want to keep your tags management separate from the text editor, you can, like Daniel says in his article, use some file-system watcher to regenerate your tags… you can even use that file-system watcher to run Gutentags’ own tag generation script directly, passing the proper options:

cd /my/project
/path/to/update_tags.sh -s /my/project/file_that_was_written

Run update_tags.sh -?, or look inside the script’s source code, to see what other options are available. Even if you don’t use Gutentags as a Vim plugin, you might want to use its sh and cmd scripts!

Combining methods

One common problem with having Vim manage the tags file is that it doesn’t know when the codebase is being modified externally – mainly when pulling/merging/etc. files in your VCS.

To fix this, many Gutentags users actually combine Gutentags with Tim Pope’s Git hook-based. After all, there’s no reason not to have the best of both worlds, where you don’t need to remember to run :GutentagsUpdate! after a git pull, and where your tags don’t go out of sync when you write code
either!

It’s a DIY world

Vim is ultimately about being able to do things your own way, so hopefully you can find yet another cool method to manage your tags, in which case you can share it with us!