View On GitHub

GitTown Tutorial

Let's assume you are part of a development team with Bob and Carol. Your repository is hosted on GitHub, and you follow GitHub Flow.

Starting a new feature

You are in the middle of the sprint and have just finished a feature. You take the next ticket from the backlog. Let's say it is called "resetting passwords". Since we are developing in feature branches, you now need to

Running git town hack reset-passwords achieves all this in a single command. This gives you the best possible start for building the new feature, on top of the latest version of the code base.

Synchronizing the branch

After coding for a while you hear that Bob shipped a number of important bug fixes, and that Carol shipped some UI design updates. Both changes affect your work, so you want them in your feature branch before you continue. On a high level, you need to

You will need to move between branches to do this, which means you also need to stash away any currently open changes in your repo temporarily. Altogether this simple operation requires between 5 and 7 individual Git commands. That's a lot of typing. And this can (should) happen several times per day, for each of your feature branches!

git town sync runs this whole process with a single command and brings you back to exactly where you started.

With Bob's bug fixes and the new UI from Carol available in your branch, any more modification you make go right on top of their work.

Creating a pull request

Once your feature is ready for review, it's time to open a pull request on GitHub. You fire up a browser, go to GitHub, navigate to your repository and finally end up on a new pull request form.

git town new-pull-request lets you jump straight from the terminal to filling in the details of your pull request in your browser. Your current branch is already selected, so all you need to do is fill out the title and description, tag the reviewers, and submit.

Shipping the feature

When your pull request gets the approval to be merged, you want to ship it. To do this safely, i.e. without breaking the master branch, you want to

This requires between 10-15 individual Git commands. Git Town provides a single, convenient command for this as well: git town ship reset-passwords.

After running this, your feature is now safely merged as a single additional commit on the master branch, the old feature branch is cleaned up everywhere, and you and the repository are ready for the next feature.