Tutorials 
Mercurial Tutorials BitBucket Previous
BitBucket
In the previous tutorial, we talked about how to work with multiple repositories, and how you can push changes from one repository out to another, and pull changes from a repository into your own.
We also discussed how on a team, it is common for everybody to have their own local repository, and a shared central repository that they each pull from and push to, when they want to share changes with others.
While there are a lot of ways that you can create this central repository, in this tutorial, I'm going to cover how to do this with BitBucket.
BitBucket is a website ([bitbucket.org bitbucket.org]) that will host Mercurial repositories in a location that all of your team members with Internet access will be able to get to. If you choose, you could even set it up so that anybody in the world can get access to it (a public repository). But that's not required. You can also have private repositories that only a select group of people can get into.
While you can pay for BitBucket, you also don't need to. In fact, the ability to have private repositories for free (a feature BitBucket's competitor GitHub does not have) is the reason why I prefer BitBucket to GitHub. Because BitBucket was historically more closely associated with Mercurial, and GitHub with Git, is another reason why I've preferred the Mercurial side to the Git side of things.
Interestingly, BitBucket supports both Mercurial and Git now while GitHub still only supports Git. So if you're split on which version control system to use, Mercurial keeps your options open.
GitHub also only allows private repositories if you pay for the service, while BitBucket lets you create private repositories with up to 5 users for free. If you think your team might expand beyond that limit, you may need to consider other alternatives or consider paying for BitBucket or Mercurial, but I suspect nearly everyone reading this will have a team no larger than five people for the near future.
Let me add one more thing to that. If you invite new users, they'll actually expand the limit up to eight. That's a nice little extra buffer. If people on your team don't have BitBucket yet, you may be able to use the invites to expand the number of users your repository can handle.
Along those lines, I'd love to get that advantage myself, so if you're creating an account on BitBucket, please consider sending me an email from the email address that you want to create a BitBucket account with, and I'll send you an invitation as soon as I possibly can. (Within minutes in many cases.) But don't feel required to do that.
Creating an Account
The first step in getting started with BitBucket is to create an account. (You can do what I said in the previous paragraph, and allow me to send you an invite, which helps me, but not you.) To create an account on BitBucket, simply go to [bitbucket.org bitbucket.org] and type in a user name, email address, and password. It doesn't look like the email address has to even be valid (when I just went through the process again, myself, it didn't force me to confirm my email address) but it will have you enter a Captcha to prove you're human. But by putting in a real email address, you can recover your password and get email updates when other people commit, both of which are nice features.
Creating a Repository.
Once your account is created, you'll be shown a welcome screen that will allow you to create a new repository or import an existing repository.
The first option is the one you'll probably want to go with. Importing an existing repository is about cloning a repository from elsewhere on BitBucket, or cloning a repository from GitHub, Google Code, CodePlex, or somewhere else on the Internet. That's a useful option, but I'll let you explore that on your own.
For the time being, you should be able to simply press the Create your first repository button.
This takes you to a new page where you can enter information about your repository. Most of this is pretty self explanatory, but there are a couple of items that are deserving of a little attention.
After name and description you'll see a checkbox for Access level. This is what you use to choose whether this is a public or private repository. If you make it public, then anybody and everybody will be able to see your code. If you're making an open source project, that's what you want. But if you're working on your own game, and you want to keep the code protected while allowing your whole team access to it (or giving yourself off-site backup, even if you're alone) you'll probably want it to be private.
The next item that deserves attention is the Forking item. Forking is functionally identical to cloning, but it represents a different concept or mental model. When you clone a repository, the intention is that you'll be pushing changes back and forth between the original and the clone. With a fork, you're not necessarily intending on ever joining the code again. You may be taking it down a different path. This idea is called forking the project (like a fork in the road). Forking projects is pretty common with open source projects, where everybody can read from the main repository, but not everyone has write access. People fork the project to create their own version, then when they've got something useful, they'll create a pull request from their version, which the person in charge of the main repository can then pull into the main version for everybody's use.
This Forking item lets you choose whether to allow forks at all, and if forks are allowed, whether to allow them to be public. If you have a private repository, you probably don't want to allow public forks, or the code could eventually get out.
Be sure to select the Mercurial repository type (but you can see here that BitBucket handles Git just as well).
There are two checkboxes by Project management labeled Issue tracking and Wiki. I usually check both of those, but consider yourself warned: BitBucket's wiki leaves a fair bit to be desired. If you want a full-featured wiki system, you'll probably need something else to supplement this.
You don't have to choose a language at all, but if you do, you'll get automatic syntax highlighting, which is pretty nice.
When you've got everything set up the way you want, you can push Create repository and finish up.
After this step, you'll have a working repository!
You should create a separate repository for every project that you have. BitBucket does not limit the number of repositories that you create. So you shouldn't feel like you need to dump everything into one repository.
A Quick Tour of BitBucket
It is worth taking a moment and showing you around and some of the features of BitBucket. Mostly, I'll leave this to you to explore on your own. The user interface is quite intuitive. It's hard to get terribly lost in BitBucket.
Along the top is a row of items that take to you to the interesting parts of your project. For instance, Source allows you to explore the current version of the source code.
The Commits tab lets you explore all of the commits that have been made to the repository, so you can explore each change in detail.
If you want to branch your code, you can use the tab marked Branches.
If someone has forked your project and sent you a pull request (they're asking you to take changes that they've made and put them in your repository) you'll use the Pull requests tab.
If you checked the Issues button when creating your repository, you'll see an Issues tab, which you can use to keep track of new ideas for features and bugs. It's actually a pretty nice feature to have this so closely tied in to the source code.
The Wiki tab lets you create an edit a wiki for your project, which can be quite useful as a way for you and your team to collaborate on how the project is supposed to work. (This may or may not fill in the role of a design document in .docx format.) But as I previously mentioned, this wiki is not nearly as powerful as, say, Wikipedia. It may or may not cut it for your needs; you'll just have to play around with it and decide for yourself.
Finally, the Downloads tab allows you to upload specific files that are downloads of the project. This makes the most sense when you're working on something like an open source project, where everybody can get to the repository, but not everyone wants to grab the code and build from source. The downloads let people just get directly to the compiled project.
Adding Code
Now that we have a project set up, it's time to get some code in there. If you already had code before trying to put the project on BitBucket, you're ready to go. Otherwise, you can start your codebase off by simply creating a new project in Visual Studio. Just the initial files that this creates should be a good starting point.
Looking Up the Project URL
The first thing you'll need to do is figure out the URL for where your project lives. You should be able to see this up in your browser's URL box, and it should come in the form of something like this:
https://bitbucket.org/[user-name]/[project-name]
There may be extra junk on the end of that URL, depending on the page you're on, but that is the information that you need, so write this down or remember it.
Adding the BitBucket Repository to Hg Workbench
I'll assume at this point that you've already got your project created and that you already set up a local repository where you've checked code in at. (This is what we've done in the previous tutorials.)
Go to your project and right-click and open Hg Workbench. (Or alternatively, go to Hg Workbench, then find your specific project under it.)
Like we did in the previous tutorial, you'll want to hit the Synchronize button ()
on the task toolbar to switch to the Synchronize task.
In the (unfortunately) unlabeled URL bar in the middle of the screen, put the URL that you looked up in the previous section:
Then hit the Save icon to the left of it.
This will ask you to put in an alias for this URL. It doesn't matter too much what you call this. It's just a label for your own sake in remembering it. (It's not shared by other people on your team or anything.) Enter one in and then hit Save.
Pushing to the BitBucket Repository
Now that we've got our BitBucket repository set up, the last step is to push our changes out to the other repository. At this point, this is almost identical to what we did before. Simply hit the Push icon ()
.
Once the transfer starts happening, you'll be prompted to enter your user name and password. This is one of the nice things about BitBucket; they handle security for you, so you can be confident that you code is safe without having to do a whole lot of work yourself. (Your mileage may vary, of course, depending on how critical what you're doing is, and how much you trust BitBucket, but for your typical indie/hobbyist/student game, I see little reason to worry too much.)
After the push is complete, you'll see a message towards the top indicating that the transfer was successful, and you should be able to go to bitbucket.org again and see your code changes over there.
Pulling Code from the Repository
The final thing we'll discuss here is how to pull changes from BitBucket down into your local repository. If somebody else already set up the project in BitBucket, this will be your starting point, instead of the previous section. But whether you started the project or not, once other people start pushing changes to the central repository on BitBucket, you'll want to pull down those changes yourself.
(If you're working alone, it will be rarer that you'll need or want to do this, but if you switch computers or something, then this will still apply.)
To pull down changes, if you haven't done so already, you should follow the same initial two steps from the previous section: figure out what the URL is, and add it to Hg Workbench.
Once you've got the repository added, it's simply a matter of pressing making sure the central BitBucket repository is selected and hitting the Pull icon ()
. This will ask you to confirm your user name and password, like when you push changes.
You should pull changes from the central repository fairly regularly. In fact, if you know there are changes there from somebody else that you don't have, you should pull them down as soon as you reasonably can to save yourself headaches later on.
Wrapping Up
We've reached the end of the Mercurial/BitBucket tutorials at this point, but there is a lot more that Mercurial can do. If you have any questions about the content that has been in these tutorials, or if there are other Mercurial related things that you want to know about, please don't hesitate to [rbwhitaker.wikidot.com/forum:start post in the forum], say something on my [rbwhitaker.uservoice.com User Voice page], or contact me directly.
These tutorials are always under continual improvement, and so if you've got a suggestion, I'd love to hear about it.
Tutorials Mercurial Tutorials BitBucket Previous
Post preview:
Close preview