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

Question

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.

Solution 1

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.

Solution 2

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.

Solution 3

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!

Solution 4

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

View more solutions

Comments

[Jason S]

more lightweight? I'm confused, coming primarily from svn where branches and tags are just different conventions for the same implementation.

[Matthew Flaschen]

@Jason, it is a little tricky. I don't think I really understood until I knew enough git to compare. However, the basic idea is that with heavy branches, the branch name is a (immutable) property of the changeset. With lightweight branches, the branch name is a shifting alias for a particular changeset. I recommend reading Branch and GitConcepts, both at the Mercurial wiki.

[Matt Joiner]

An unexpected analogy O_O

[John Lawrence Aspden]

I don't get this analogy. Am I writing the book or reading a book that someone else is writing? Is the publisher version controlling the manuscripts? Is he stamping my copy or his? Am I writing manuscripts, photocopying them? Working on them with tippex? Doing it on computer and versioning it somehow?

[00dani]

This analogy is quite confusing and could use refining. Try this. You're reading a book. 1 page = 1 changeset. * A tag is sticking a sticky note on a page you find interesting. It stays on the same page and can be used to find that page easily. * A named branch is a chapter. Every page has a chapter number written in the margin. This groups related pages together. * A bookmark is a bookmark. As you move from page to page, you move the bookmark forward with you. You can use multiple bookmarks to keep track of progress through different parts of the book.

[Giscard Biamby]

I found the analogy more confusing than the literal explanation (tags: label for a specific changeset; is part of the changeset in the permanent history of the repo. bookmark: pointer to the tip of a branch; stored separately from changesets, and sometimes likened as similar to "lightweight" branches in git).

[Sled]

I found this analogy less helpful that the answer by Matthew Flaschen.

[Florian Pilz]

This answer is great if you already have a thought or two how things are working. I think it's well done. :)

[nasch]

You might want to consider hg-flow, it's very useful.

[monkeyjumps]

what if you create a feature branch or a bookmark and that feature never gets merged into master? Whats best practice at this point if one wants to clean up the repo?