Use a Mercurial bookmark to update a file
- Create a Mercurial repository
- Copy your Mercurial repository and add source files
- Pull changes from your Mercurial repository on Bitbucket
- 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:
Go to your terminal window and navigate to the top level of your local repository using the following command:
$ 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:
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.
- 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.
- Open the
crewrolesfile using your preferred editor.
Make a change to the file by adding the following crew member:
<p> Max Taylor<br> <b>Server Engineer</b> </p>
<p>Bitbucket Space Station crew members:</p> <p> Emma Paris<br> <b>Quality Assurance</b> </p> <p>
- Save and close the file.
hg statusin the terminal window. You will see something like this:
$ hg status
hg commitcommand 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
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:
Go to your terminal window and navigate to the top level of your local repository.
$ cd ~/repos/bitbucketstationcrew/
hg bookmarkscommand to check a list of all your bookmarks. The * indicates the bookmark you have checked out.
$ hg bookmarks
* spacelaboratory 30658:2dc7d086f314
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:
Because you don't plan on using
spacelaboratoryanymore, you can delete the bookmark.
$ hg bookmark -d spacelaboratory
hg bookmarksto see that the
spacelaboratorybookmark no longer exists.
$ hg bookmarks
* @ 30658:2dc7d086f314
- 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:
Navigate to the repository directory in your terminal window and enter
hg push -B
@to push the changes. The
hg pushtells the terminal to push the @ bookmark. It will result in something like the following:
$ hg push -B @
pushing to https://email@example.com/emmap1/bitbucketstationcrew
http authorization required for https://bitbucket.org/emmap1/bitbucketstationcrew
realm: Bitbucket.org HTTP
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 @
Click the Overview page of your Bitbucket repository, and notice you can see your push in the Recent Activity stream.
- 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
spacelaboratorybookmark never interacted with Bitbucket, only the change we created and committed.
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.
- Click Source, and then select the
You can see the last change to the file has the commit id you just pushed.
- 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.