Tutorial

As a follow up to my Basic’s post of Source Control, I’m going to show you how to setup Mercurial (Hg) for source control. First, I’m going to show you how to install Mercurial on your workstation. Next, we’re going to set up a central repository using Bitbucket. Afterwards, we’re going to go over the major workflows when working with Mercurial. To wrap up this tutorial, I’ve included some additional resources that helped me understand Mercurial when I first started using it.

Installing Mercurial

Installing Mercurial is very easy, just click here to download the installer for TortoiseHg for Windows. However, if you’re running Mac, the workflow is going to be a little more complicated.

  1. Download Mercurial from here (it will be a ZIP file)
  2. Expand the ZIP file and run the MPKG file to install
  3. Follow the prompts to complete the installation
  4. After installation, open the command prompt and enter the following: hg –version (should see version information
  5. Next, you need to check if there’s a .hgrc file by entering: ls ~/.hgrc
  6. If there isn’t, create it by using touch: touch ~/.hgrc
  7. After creating, open it using your favorite text editor
  8. In the text editor, enter the following: username = Name To Appear <email address>
  9. Save and close the file
  10. Congratulations, you now have Mercurial on your workstation.

Working with Mercurial

When using Mercurial, you have two options: you can use the UI (TortoiseHg for Windows or SourceTree for Mac), or you can use the command prompt. For this tutorial, I’m going to show you how to work with Mercurial using the command prompt. Not only is it just as easy as the UI, but if you’re like me and use both Windows and Mac for development, it’s nice to have one tool that behaves the same on both environments.

Using Bitbucket to Host Your Central Repository

Why Use Bitbucket?

As part of using any source control, there still needs to be a server to host the central repository. When it comes to setting a server, you could setup your own server, use the command “hg serve” to activate a lightweight server, or you could use Bitbucket. Each of these options have merit depending on your situation, but my go-to solution is to use Bitbucket. Bitbucket is essentially a server that hosts repositories for their users (similar to GitHub) but unlike GitHub, Bitbucket supports both Git and Mercurial for source control and offers many cool features like unlimited repositories, providing a wiki and bug tracking capabilities.

Great, since we’ve decided to use Bitbucket to host our central repository, why don’t we go ahead and set that up now?

Setting up a Central Repository

  1. Create an account for Bitbucket and login
  2. After logging in, you should be at the Dashboard, choose Create Repository
  3. Next, you should see a dialog for Creating a New Repository. For this example, let’s call the repo “Simple Repo”
  4. Set the Repository type to Mercurial and click ‘Create Repository’
  5. After creating the repository, you’ll see an option for adding code, choose the “I’m starting from scratch option’
  6. Follow the steps for creating a directory and copy the “hg clone” command to your command prompt
    1. For this example, I created C:\Dev\ to use for development
  7. After running the “hg clone” command, you may be prompted for your password.
  8. If everything works, you should see a folder in the directory you created called “simple-repo”
    1. For this example, in C:\Dev\, I would see a folder called “simple-repo”
  9. Congratulations, you’ve successfully created your first repository on Bitbucket and have copied it your workstation.

Time To Start Developing

Great, you have this empty repository, but it’s time to start developing. While developing software, your workflow is going to look a lot like this:

  1. Add files / Modify files
  2. At certain intervals, committing these changes to your local repository
  3. If necessary, pull latest changes, update local repository, and merge
  4. Commit any outstanding changes to the local repository
  5. Repeat steps 1 through 4 until you’re ready to share your changes with the rest of the team.
  6. Push changes to the central repository
  7. Start from Step 1

Adding Files

An empty repository is nice and all, but if we’re going to get anything done, we need to add some files to the repository. It’s easy to add files to Mercurial using the command prompt.

  1. Create a file (I called mine Grocery_List.txt)
  2. Move the file to the repository folder
    1. For this example -> C:\Dev\simple-repo
  3. In the command prompt, navigate to your local repository and run the “hg status” command
  4. You should see a question mark “?” followed by the name of the file you created.

So what’s the deal with the question mark and what does the “hg status” command do? “hg status” provides a way to see what changes have been made to your local repository since the last push. Since we have never performed a push, it’s letting us know that there is a file in the repository called Grocery_List.txt and that it’s not being tracked by Mercurial (hence the “?”). Other options include “A” (for files that were newly created and added), “M” (for files that have been modified),  and “R” (for files that Mercurial has removed). There are other symbols, but these are the more common symbols to see.

Now that we have this file, we need to tell Mercurial to track this file. In order for Mercurial to track the file, we need to add the file to the repository by using the “hg add” command. This command is pretty simple, just enter ‘hg add Grocery_List.txt’ and Mercurial will add the file to the local repository. When working with the “hg add” command here are some slick tricks to use when adding files

  • hg add (adds every file in every folder for the repository to track)
  • hg add ‘NameOfFile’ (adds just the file with the name)
  • hg add *.txt (adds all .txt files in the current directory)

After adding Grocery_List.txt to the local repository, if we run the “hg status” command, we’ll see that Grocery_List.txt now has a new symbol “A”.

Committing Files

After making changes to the repository (adding files), it’s time to commit these changes to our local repository. In Mercurial, to commit changes to the local repository, we need to use the “hg commit” command. After using this command, a text editor will appear. All we need to do is to enter a comment about what we changed. For this example, I’m going to write that is my initial commit and then I’m going to save the text document. Gotcha: If you don’t save the text file, then the “hg commit” command fails. It forces the user to enter something for a comment.

After committing this change, if we were to run the “hg status” command, you’ll get a message saying that there aren’t any changes. But wait a minute, we just committed changes to our local repository, not the central repository, so why don’t we have changes? It’s really easy, it’s because the “hg status” command only looks for changes based off what our latest local repository has. Since we just committed changes to our local repository, “hg status” return nothing.

Making and Reviewing Changes

Alright, we’ve committed our first file. We’re done now right? Not quite, as part of developing software, you’re going to be making changes all over the place. In this regard, we’re going to explore how Mercurial reacts to files that have changed and how we can review what changes we’ve made to a file.

To begin, let’s open Grocery_List.txt and make some changes. In this example, I’m going to add some items for me to pick up at the store. After saving your changes, run the “hg status” command. This time you should see Grocery_List.txt is listed with a new symbol ‘M’. This means that (M)odifications have been made to the document. To see what has changed, you can use the “hg diff” command to see what changes have been made to the file between revisions. The default behavior is to compare what changes have been made since the last commit to the local repository.

Using the “hg diff” command is great for reviewing what changes have been made between commits of the local repository (if you’re like me and don’t keep track of all the things you change between change sets, then the “hg diff” command is a lifesaver). Like the “hg add” command, there are a number of shortcuts that can be used to diff on certain files and options to diff files between revisions.

After making the changes and ensuring that Grocery_List.txt has been marked for modifications, let’s go ahead and commit that change using the “hg commit” command.  Congratulations, you just finished making some changes to your local repository and now it’s time to start pushing those changes to the rest of your team.

Pushing Changes

Great, so you’ve been making changes to your local repository, but now it’s time to push these changes to the rest of your team. Like most Mercurial commands, pushing changes is pretty simple, just use the “hg push” command. This will push each change in the local repository back to the central repository for your team to access.

  1. In the command prompt, navigate to your local repository (C:\Dev\simple-repo)
  2. Type “hg push”
  3. You may be prompted for a password, enter it here
  4. A message will be printed showing what files have been added and the number of change sets.

My Push failed, what’s up?

When you’re about to push changes to the central repository, the push will fail if you don’t have the latest copy of code. I like to think of this as a fail safe so you don’t accidentally commit old code or code that depends on other files that have since changed. If this happens, see below on how to pull and merge changes.

Pulling and Merging Changes

It’s great that you finally made changes to the central repository, however, as development continues, you’re not the only developer making changes. A fair question is how do I know if I have the latest source code? And if I don’t have the latest source code, how can I grab the latest without losing my changes?

Thanks to the Mercurial command “hg pull”, grabbing the latest changes is a breeze. Navigate to your local repository via command prompt and enter “hg pull”. This command will grab the latest source code from the central repository. However, the “hg pull” command doesn’t automatically update your local repository. You will need to run the “hg update” command to update to the latest version.

Sometimes, running the “hg pull” command will give you a message about multiple heads. All this means is that there are you don’t have all the changes and that some of the files you’ve changed have also been modified. Mercurial is very helpful when it tells you use “hg merge” to merge the files. The “hg merge” command takes your copy of the file and merges it with the latest version. If there are no conflicts, then the merge works and it’s up to you to verify that the software is behaving correctly.

However, merging isn’t always that easy. For example, let’s say that I modified Grocery_List.txt so that it says 2 dozen eggs. However, if before I push my changes, another dev modified the file to say 2 pounds of bacon, then that will cause a legitimate conflict that I would have to resolve it before I could commit my changes.

When handling conflicts, you get a spiffy interface (called KDiff3) that allows you to pick which version is correct (it even allows you to pick both versions, see here for a great example of handling merges). After handling the conflicts, you’re ready to commit your changes and attempt to push your changes back to the central repository.

Wrapping Things Up

Congratulations, you just finished setting up Mercurial for your source control! I know it’s a lot of information to take in, but trust me, you’re work is going to improve once you start using source control. In this tutorial, you’ve learned how to install Mercurial on your workstation, setup a central repository using Bitbucket and the major workflows of working with Mercurial to handle your source code (adding/modifying files, pulling and merging changes, and pushing your changes).

Now, there is still plenty to learn about Mercurial, but you now have the foundation from which to start experimenting with Mercurial.

Additional Resources

Basics

As the first part of the Basics of Software Development series, we’re going to talk about source control is, why you should be using it and commonly used source control management (SCM) tools.

Source Control, what’s that?

To put it simply, SCM is a set of tools that allow users to keep track of source code by using a repository. The most common workflow is to get a copy of the source code from SCM, make changes to some of the files (refactoring for example) and committing those changes back.

Benefits of Source Control

  • Allows for users to undo uncommitted changes
    • Promotes developers to refactor code
  • Keeps track of what changes have been made over time
    • Great for seeing what changes have been made over time (for example between versions)
  • By definition, it’s a backup of the source code
    • Perfect if your workstation crashes and you don’t have a backup
  • Makes it easier for other developers to get the latest changes
    • Instead of one developer making changes and “pushing” them to the team, source control allows the team to “pull” changes when ready.

Without source control, anytime that code changes were made, the developer who made changes would have to push the code to the other developers. This may not sound terrible, but what if you were in the middle of rewriting a file? You would have to figure out what files have been changed, hope that the files that were changed aren’t files that you’re currently working on. After ensuring all of that, you need to merge your changes to the latest version and hope that nothing broke. As you can see, this is a horrible workflow, prone for errors. However, using a SCM solves these issues.

Choosing Source Control

All SCM tools work either as centralized or distributed. Before you can choose a source control, you need to figure what type of source control type works best for your situation (tech requirements, ease of setup, company policies, etc..)

In a centralized source control implementation, there is a main server (central repository) that holds the source code and history of changes. When a developer checks out source code, they are only getting the source code (no revision history). After the developer makes changes and commits the changes, the files that have been modified are sent back to the central repository. Since the repository has the source code and history of changes, the repository is known to have the “blessed” or the “single source of truth” copy of the source code.

Since the centralized implementation utilizes the central server, it’s very easy to see what’s the latest and greatest. However, due to the centralization, if the server ever goes down, the team cannot commit changes.

In a distributed source control implementation, the big difference is that there is not a central repository. This means that every developer has both the latest source code and the revision history.

The main advantage to this implementation is that a developer can commit changes and continue working if there is no network connection. However, due to the lack of a central repository, there is no such thing as “blessed” version.

Common Source Control Implementations

Team Foundation Server (TFS) – This is a centralized source control that is most likely working with .NET code and Visual Studio. Even though It is possible to use TFS for other languages and IDE’s, you have to use Team Explorer Everywhere and is currently supported with Eclipse.

Subversion (SVN) – This is a centralized source control platform that is designed to be used for any programming language and IDE.

Git – This is one of the most widely used distributed source control platform. This platform is most commonly used with GitHub.

Mercurial – Another common distributed source control platform. This is most commonly used with Bitbucket.

Visual SourceSafe – Very old solution from Microsoft, if your company is using this for source control, you need to run away screaming  migrate to another solution. This was the precursor for TFS and should no longer be used for source control.

Additional Reading / Further Resources:

Other

Woot! First post….

Who am I and how did we get here?

My name is Cameron Presley and it’s time for a short story about why this blog exists and it’s purpose.

After graduating college, I started working for a big company and I was really excited to finally write “big boy code”.  However, as time progressed, I started to feel like more of a cog in the machine instead of a developer. Unrealistic deadlines, not able to propose solutions, insanely steep learning curve with no help, it just kept getting worse and worse. A company that frowned upon refactoring code, disgusted with changing legacy code, and not giving support to new developers, this company was a huge stress inducer. For all intents and purposes, I was a code monkey. Big shocker, after about a year, I left the company to try my luck elsewhere.

Fortunately, I was able to find a company and a team lead that was willing to mentor the new guy and not just throw him to the sharks. Thanks to my team lead, I’ve learned a lot about what developing software means and it’s not as simple as just writing an if statement. There are so many nuances when it comes to development: designing the solution, ensuring the solution is correct, working with managers and members of a team. Without his help, the chances of me succeeding would be very low indeed. In that regards, I’m lucky that there was someone who cared about producing good software and wanted to share his knowledge with me.

However, I know that there are many developers out there who don’t have a mentor to learn from. These new developers are the ones that need the information from this blog the most. There are too many nuances that are not taught in academia that needs to be discussed. The main goal of this blog is to provide resources for new developers to help ease the transition from writing software in academia to writing software for the masses. Whether that’s providing soft skills (communication with others) or more hard skills (setting up a continuous integration engine), I want to provide my experience and be the mentor to those who may not have one.

Wish me luck and enjoy

-Cameron