How Teams Use Git for Big Projects

Every time a new member joins our team we have to guide him through our Git workflow. So I decided to write everything here in order to simply send them the link (and help others interested in learning how a real development team uses Git).

So, we will assume you know what Git is, if not, please make sure you read AND understand (at least) the first 3 chapters from here: http://git-scm.com/book

Repositories

Every project has its own repository owned by the company which we call upstream. As you start working on an existing project, you will receive access to its Git repository belonging to your organization’s account on BitBucket or GitHub. When a new developer joins the team and starts to work on this project, he or she will need to make a fork of the upstream repository (from the web interface). This fork is a copy of the original repository, now owned by the developer. This new repository is called origin.

So the first thing to remember is the upstream and origin names and their meaning: upstream is the original, company owned, repository, while the origin is a copy, owned by the developer. Every developer will have his/hers origin repository!

After you create your fork, you will have to clone the repository (the origin) on your development machine. To do this use the git clone command:

git clone [your repo ssh url]

Now, that you have the origin locally (check with git remote -v) let’s also add the upstream:

git remote add upstream [upstream repo ssh url]

To see the result, run git remote -v. Both origin and upstream should be listed.

Common Branches

We generally use 3 types of branches: master, release and the development branches.

The master branch has the code that is currently running in production and the release gathers all the code ready to be merged into master and deployed live.

For every task/story you have to create a new branch from the current release having the name formatted like this: [story_ID]-[intuitive name]-[team name (optional)]. Note that you will use your origin repository to create new branches so this means you will have to make sure your release branch is up-to-date with the latest code form upstream:

git checkout release
git pull upstream release
git push origin release
git checkout -b [branch name]

Workflow

As previously stated, when works starts on a new task/story, a new branch is created from the release branch. You will develop and commit in this branch until you’re done. You are encouraged to commit as often as possible:

git add [file to be commited]
git commit -m “commit message"
git push origin [branch name]

We recommend to check what is to be committed first, by running the git status and git diff commands, then adding each file individually (or group of files) to the commit.

Avoid adding everything to the commit because this will often lead to unwanted changes to be committed and your code will fail CR (code review).
git add .

When you’re done, push the branch on the upstream repo so others can access it:

git push upstream [branch name]

After this, create a pull request from this new branch to the upstream release branch and send the story to QA and CR (together with the pull request url).

If everything is ok, the code will be merged into the release branch to test it together with other changes made by you or colleagues developers when working on different stories. When everything is ready to be deployed, the release branch (the upstream release) will be merged into the master and the code will end up on the production server.

Congratulations! Now that you know how to use Git, take a break and have a laugh at those who don’t: