67

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.

Vadim Kotov
  • 8,084
  • 8
  • 48
  • 62
Jason S
  • 184,598
  • 164
  • 608
  • 970
  • 3
    You may find this guide about branching in Mercurial very helpful: http://stevelosh.com/blog/2009/08/a-guide-to-branching-in-mercurial/ – alexandrul Mar 22 '11 at 21:50

4 Answers4

33

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.
hurrymaplelad
  • 26,645
  • 10
  • 56
  • 76
gizmo
  • 11,819
  • 6
  • 44
  • 61
  • 9
    An unexpected analogy **O_O** – Matt Joiner Mar 23 '12 at 08:19
  • 38
    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? – John Lawrence Aspden Apr 18 '12 at 20:45
  • 20
    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. – 00dani Jul 21 '12 at 03:05
  • 9
    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). – Giscard Biamby Oct 10 '12 at 14:19
  • I found this analogy less helpful that [the answer by Matthew Flaschen](http://stackoverflow.com/a/5385839/254477). – Sled Oct 30 '12 at 13:41
  • 3
    This answer is great if you already have a thought or two how things are working. I think it's well done. :) – Florian Pilz Dec 11 '13 at 06:57
24

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!

John Lawrence Aspden
  • 17,124
  • 11
  • 67
  • 110
  • 1
    You might want to consider hg-flow, it's very useful. – nasch Dec 01 '18 at 15:56
  • 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? – monkeyjumps Feb 12 '19 at 16:42
24

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.

Matthew Flaschen
  • 278,309
  • 50
  • 514
  • 539
  • more lightweight? I'm confused, coming primarily from svn where branches and tags are just different conventions for the same implementation. – Jason S Mar 22 '11 at 01:56
  • 1
    @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](http://mercurial.selenic.com/wiki/Branch) and [GitConcepts](http://mercurial.selenic.com/wiki/GitConcepts), both at the Mercurial wiki. – Matthew Flaschen Mar 22 '11 at 03:04
12

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

Ry4an Brase
  • 78,112
  • 7
  • 148
  • 169