Copy your Mercurial repository and add source files

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

Now that you have a place to add and share your space station files, you need to copy it to your local system. To set that up, you want to copy the Bitbucket repository to your system. Mercurial refers to copying a repository as "cloning" it. When you clone a repository, you create a connection between the Bitbucket server and your local system.



You are about to use a whole bunch of Mercurial and non-Mercurial commands from a terminal. If you've never used the command line before, learn how to set it up at The Command Line Crash Course .

Step 1. Clone your repository to your local system

Open a browser and a terminal window from your desktop. The terminal window on your local system is the system you code on as opposed to the remote Bitbucket server. After opening the terminal window, do the following:

  1. Navigate to your home (~) directory.

    $ cd ~

    As you use Bitbucket more, you will probably work in multiple repositories. For that reason, it's a good idea to create a directory to contain all those repositories.

  2. Create a directory to contain your repositories.

    $ mkdir repos
  3. From the terminal, update the directory you want to work in to your new repos directory.

    $ cd ~/repos
  4. From Bitbucket, go to your BitbucketStationCrew repository.
  5. Click the + icon in the global sidebar and select Clone this repository.
    Bitbucket displays a pop-up clone dialog. By default, the clone dialog sets the protocol to HTTPS or SSH, depending on your settings. For the purposes of this tutorial, don't change your default protocol.

    • A. Clone button: Click this button to clone a repository.
    • B. Protocol, clone command: Pick HTTPS or SSH and copy text to the command line.
  6. Copy the highlighted clone command.
  7. From your terminal window, paste the command you copied from Bitbucket and press Return.

  8. Enter your Bitbucket password when the terminal asks for it. If you created an account by linking to Google and you are following this tutorial, you should have created a password already. 

    At this point, your terminal window should look similar to this:

    $ cd ~/repos
    $ hg clone
    http authorization required for
    realm: HTTP
    user: emmap1
    destination directory: bitbucketstationcrew
    no changes found
    upgrading to branch default
    0 files updated, 0 files merged, 0 files removed, 0 files unresolved

    You already knew that your repository was empty right? Remember that you have added no source files to it yet.

  9. List the contents of your repos directory and you should see your bitbucketstationcrew directory in it.

    $ ls

Congratulations! You've cloned your repository to your local system. Now you can add a file so you have some content.

Step 2. Create the @ bookmark and a file for that bookmark

With the repository on your local system, you can use it to start keeping track of all your space station employees. To do so, let's create a file about your crew members on the main bookmark.

A bookmark represents a line of development for your repository. Think of a bookmark as a pointer to commits. This pointer keeps track of the last things you committed. If you work with bookmarks, you can have as many lines of development that you want. For now, we are just going to start out with the main bookmark, which Mercurial refers to as @To create a file for the @ bookmark, you have to create the bookmark first. 

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

    $ cd ~/repos/bitbucketstationcrew/
  2. Enter this line in the terminal to create the @ bookmark: 

    $ hg bookmark @
  3. Enter hg bookmarks to see that the bookmark exists and is checked out.

    $ hg bookmarks
     * @                         30658:2dc7d086f314

    The * indicates that the bookmark is checked out. If you had more bookmarks, this list would also include them.

  4. Enter the following line into your terminal window to create a new file with content.

    $ echo "Emma Paris" >> crew.txt

    If the command line doesn't return anything, it means you created the file correctly!

  5. Get the status of your local repository.

    The hg status command tells you about how your project is progressing in comparison to your Bitbucket repository. You should see something like this:

    $ hg status
    ? crew.txt

    You can see that Mercurial is aware that you created a file in your local repository and haven't added it yet.

  6. Tell Mercurial to track your new crew.txt file using the hg add command.

    $ hg add
    adding crew.txt

    The hg add command gets crew.txt for addition during the next commit. This is the point where you prepare a snapshot of a set of changes before committing them to the official history.

  7. Check the status of the file.

    $ hg status
    A crew.txt

    Now you can see the new file has been added and you can commit it when you are ready. The hg status command displays the state of the working directory. You’ll want to run this in conjunction with hg commit to see exactly what’s being included in the next snapshot.

  8. Issue the hg commit command with a commit message, as shown on the next line. The -m indicates that a commit message follows. Just like when you created a file, the hg commit command doesn't return anything when you enter it correctly.

    $ hg commit -m 'Initial commit'

    The hg commit command takes the working directory and commits it to the project history. Combined with hg add, this process defines the basic workflow for all Mercurial users.

Up until this point, you have done everything on your local system and nothing is visible to your Bitbucket repository until you push those changes.

Step 3. Push the file to Bitbucket

  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
    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 @

    Pushing moves a series of commits to another repository, which serves as a convenient way to publish contributions.


  2. Go to your BitbucketStationCrew repository in Bitbucket and click the Commits item in the sidebar.

    You should see a single commit on your repository. Bitbucket combines all the things you just did into that commit and shows it to you. You can see that the Author column shows the value you used when you configured the Mercurial global file ( ~/.hgrc).

  3. Click the Source link.
    You should see that you have a single source file in your repository, the crew.txt file you just added.

Remember how the repository looked when you first created it? It probably looks a bit different now.


Last modified on Jun 28, 2017

Was this helpful?

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