what's the difference between hg tag and hg bookmark?

What's the difference between a tag and a bookmark in Mercurial? I can't seem to find any discussion of how the two differ.

Lets consider your repository as a "choose your own adventure books", with different points of view.

• A tag is like a stamp that the editor put on your manuscript to say "ok, we keep a trace of your current work, in case shit happens."
• A named branch would be a chapter. You have to choose at one point which chapter you'll have to write, and they are there to stay. Some will merge back, some will end (sorry, you died.)
• A bookmark is, well, a bookmark. It follows you while you're reading (committing) the book. It helps you to keep tracks of "what you were reading at that time", so you can remove them, move them to a different "chapter". When you share the book (push), you usually don't share your bookmarks, unless you explicitly want to. So you usually use them on anonymous branches because their life cycle is shorter than named branches.

Bookmarks are used when you want a mnemonic (foo_feature) that points to a changing commit id as your work progresses. They're more light-weight that regular Mercurial branches, and somewhat similar to the way git branches work.

Tags generally point to fixed commit ids. They can be reassigned manually, but this is discouraged.

There are actually five concepts to play with:

• tags
• local tags
• bookmarks
• lightweight branches
• named branches

Lightweight branches are what happens if you just use mercurial. Your repository history forks and sometimes merges as you change things and move around your history.

The other four are ways of annotating lightweight branches and the changesets that make them up.

named branches and tags are mercurial-only concepts where the branch names and tags actually get recorded in the repository by making more commits to the repository. They'll tend to propagate to other repositories in ways which are not necessarily obvious.

local tags and bookmarks are much more like what git calls tags and branches. They're metadata rather than being mixed in with the versioned objects. So they're not represented as part of the repository history. They tend to be local to your repository, and won't propagate unless you propagate them deliberately.

At least I think that's how they all work. After about twelve months of using mercurial daily I haven't really got to grips with its model(s). If anyone knows better than me then feel free to edit this answer so it's correct.

---

How I actually use these things in practice.

I'm working on a single shared repository with about 20 other people. I make many experiments and lightweight branches in my own private repository, which never get pushed to our main central repository. Occasionally once an experiment has worked out I'll modify the main line and push a changeset into the central repository, from which it will find its way to everyone else's machine.

I'll occasionally push some changesets to a co-worker if they're one of the people who's comfy with how mercurial works. But several people are a bit scared of it and prefer if I send them diffs that they can apply with patch.

For experiments I expect to be short lived and private, I just let lightweight branches happen where they may, and remember what's going on. If I feel my memory slipping about a twig that's been around for a bit, I bookmark it.

I use local tags to mark revisions I might like to come back to one day. They make interesting past states easier to find.

I myself almost never make non-local tags or named branches (except by accident, and I destroy them if I do). But our release people do. Our released major versions all have their own named branches off from the main line, and minor versions have tags on those branches. That ensures that these important branches and tags look the same to everyone.

Again, I've no idea whether this is how one's supposed to use mercurial, but it seems to be a model that works well for our size of team.

If three or four of us wanted to collaborate on an experiment, that would probably be worth a named branch, which we'd probably share between ourselves but not push to the central repo. I don't know how well that would work out!

The biggest difference is that a bookmark is automatically moved forward when you commit. Here's an example:

hg init
..edit a file..
hg commit -m 'my commit' # creates revision 0
hg tag -r 0 mytag     # creates revision 1
hg bookmark -r 0 mybookmark   # doesn't create a revision
hg update 0   # get back to r0
..edit a file..
hg commit -m 'another commit'  # creates revision 2

At that point mytag is still pointing to revision 0 and mybookmark is now pointing at revision 2. Also the tagging created a changeset and the bookmark didn't.

Also, of course, the bookmark created a revisio