Use a Mercurial bookmark to update a file

Still need help?

The Atlassian Community is here for you.

Ask the community

  1. Create a Mercurial repository
  2. Copy your Mercurial repository and add source files
  3. Pull changes from your Mercurial repository on Bitbucket
  4. Use a Mercurial bookmark to update a file

You are opening a laboratory in your space station with a new team member! The only thing is that the laboratory is not running yet, so the new team member isn't ready to start either. What do you do? Learning about feature bookmarks will allow you to update your files and only add the new team member when you're ready.

Bookmarks are most powerful when you're working on a team. You can work on your own part of a project from your own bookmark, pull updates from Bitbucket, and then merge all your work into the main bookmark when it's ready.

Just as the @ bookmark is a pointer to to the main line of development, a feature bookmark is a pointer to the line of development for a feature that you aren't ready to include in the main area of development. This pointer has its own development area and project history. The following diagram shows two bookmarks:  @  and another bookmark that includes a bug fix.

Step 1. Make a change

Create a bookmark where you can add teammates who work in the laboratory and that you aren't ready to commit. When the laboratory has its grand opening, you can merge the file and then delete the no-longer-needed bookmark.

To start using a feature bookmark, do the following:

  1. Go to your terminal window and navigate to the top level of your local repository using the following command:


    $ cd ~/repos/bitbucketstationcrew/

    Windows Command Prompt

    $ cd repos/bitbucketstationcrew/

    Because bookmarks are just pointers to commits, when you create a bookmark, all Mercurial needs to do is create a new pointer—it doesn’t change the repository in any other way. So before you begin your repository looks like this:


  2. Create a feature bookmark for the line of development about your space laboratory:

    $ hg bookmark spacelaboratory

    This command creates and activates that bookmark, so your repository looks something like this:

    The repository history remains unchanged. All you get is a new pointer to the current commit.

  3. Navigate to the directory folder containing your repository files (something like /Users/<youruser>/repos/bitbucketspacestation). You will notice there are no extra files or folders in the directory.
  4. Open the crewroles file using your preferred editor.
  5. Make a change to the file by adding the following crew member:

        Max Taylor<br>
        <b>Server Engineer</b>


    <p>Bitbucket Space Station crew members:</p>
        Emma Paris<br>
        <b>Quality Assurance</b>
        Max Taylor<br>
        <b>Recreation Department</b>
  6. Save and close the file.
  7. Enter hg status in the terminal window. You will see something like this:

    $ hg status
    M crewroles
  8. Enter the hg commit  command in the terminal window, as shown by the following:

    $ hg commit crewroles -m "Making a change"

    Now your repository looks something like this:

    It's time to move the change you just made into the @ bookmark.

Step 2. Moving bookmarks forward

The space laboratory is ready! It's time to make your new team member part of the entire team. You can move bookmarks forward when there is a linear path from  to the current bookmark. Because you have only created one bookmark and made one change, all we need to do is move the bookmark of the main line of development, which Mercurial refers to as @, to our new head.

This move effectively combines the histories, since all of the commits reachable from the spacelaboratory bookmark are now available through the main one.  Because you don't need to have a separate place to add space laboratory team members anymore, it's probably a good idea to delete the  spacelaboratory  bookmark.

This bookmark workflow is common for short-lived topic bookmarks with smaller changes and are not as common for longer-running features.

To move your bookmark forward, do the following:

  1. Go to your terminal window and navigate to the top level of your local repository.


    $ cd ~/repos/bitbucketstationcrew/

    Windows Command Prompt

    $ cd repos/bitbucketstationcrew/
  2. Enter the  hg bookmarks  command to display a list of all your bookmarks. The * indicates the bookmark you have checked out.

    $ hg bookmarks
       @                         26432:d6f92e6b6d94
     * spacelaboratory           30658:2dc7d086f314
  3. Enter hg bookmark @  to move the main bookmark forward:

    $ hg bookmark @
    moving bookmark '@' forward from d6f92e6b6d94

    Now you've moved the pointer for the @ bookmark forward to the current head, your repository looks something like this:

  4. Because you don't plan on using spacelaboratory anymore, you can delete the bookmark.

    $ hg bookmark -d spacelaboratory
  5. Enter hg bookmarks to see that the spacelaboratory bookmark no longer exists.

    $ hg bookmarks
     * @                         30658:2dc7d086f314
Congratulations! Here's what you've done so far:
  • Created a bookmark and checked it out
  • Made a change in the new bookmark
  • Committed that change to the new bookmark
  • Integrated that change into the main line of development
  • Deleted the bookmark you are no longer using

Next we need to push all this work back up to Bitbucket.

Step 3. Push your change to Bitbucket

You want everyone to see your updates about the new team member. To make those visible, you can publish the current state of your local repository to Bitbucket. This diagram shows what happens when your local repository has changes that the central repository does not have and you push those changes to Bitbucket.

To push your change to Bitbucket, do the following:

  1. Navigate to the repository directory in your terminal window and  enter hg push -B  @  to push the changes. The -B  @ part of hg push tells the terminal to push the @ bookmark. It will result in something like the following:

    $ hg push -B @
    pushing to
    http authorization required for
    realm: HTTP
    user: emmap1
    searching for changes
    remote: adding changesets
    remote: adding manifests
    remote: adding file changes
    remote: added 1 changesets with 1 changes to 1 files
    exporting bookmark @
  2. Click Commits and you can see the commit you made on your local system. Notice that the change keeps the same commit id as it had on your local system.

    You can also see that the path (the line to the left of the commits list) looks straight forward and shows no bookmarks. That’s because the spacelaboratory bookmark never interacted with Bitbucket, only the change we created and committed.
  3. Click Branches and notice the page has no record of the bookmark either.

    When looking for Mercurial bookmarks, you can find them under the Branches page in Bitbucket.

  4. Click Source, and then select the  crewroles  file.
    You can see the last change to the file has the commit id you just pushed.
  5. Click the file history list to see the committed changes for this file, as shown in the following figure.

You are done!

That was intense! Maybe. Depends on how it compares to launching into space. Now that you know a lot more about Bitbucket, you are now prepared to run your space station's activities a lot better. Now, take a break and go do some star gazing.

Want to learn more about Bitbucket and Mercurial? You can take on the challenge of updating a teammate's repository.

Not sure you will be able to remember all the Mercurial commands you just learned? No problem. Bookmark our Git and Mercurial commands page so that you can refer to it when needed.

Last modified on Oct 30, 2018

Was this helpful?

Provide feedback about this article
Powered by Confluence and Scroll Viewport.