Working with branches in Git

Introduction

Why use branches

Branches help separate different projects so that it is easy to only push out finished projects. Branches also tend to be easier than using cloned directories for pulling in changes and share changes across multiple projects.

http://www-cs-students.stanford.edu/~blynn/gitmagic/ch04.html had this to say about branches in git:

You might wonder if branches are worth the bother. After all, clones are almost as fast, and you can switch between them with cd instead of esoteric Git commands.

Consider web browsers. Why support multiple tabs as well as multiple windows? Because allowing both accommodates a wide variety of styles. Some users like to keep only one browser window open, and use tabs for multiple webpages. Others might insist on the other extreme: multiple windows with no tabs anywhere. Others still prefer something in between.

Branching is like tabs for your working directory, and cloning is like opening a new browser window. These operations are fast and local, so why not experiment to find the combination that best suits you? Git lets you work exactly how you want.

Also, an added benefit that may become of use to our group is that branches can also be shared between users.

Overview on how to use branches

Git's paradigm for branches is that there is one working directory, one staging area, and multiple commit histories. One way to think about this is when you switch between branches you are populating your working directory with the files for that particular branch.

It is recommended that you leave your master branch clean of any but the shortest of projects. This is primarily because it provides users a clean branch to use to make minor changes without worrying about accidentally pushing out half-baked projects. It also has the added benefit of simplifying how to use git pull and git push when you have more than one branch. This page is presented assuming that you are following this paradigm.

For any project that is going to take any substantial amount of time, it is recommended that you store these changes in a branch. When naming a branch, please preface the name of the branch with your user name to avoid accidentally sharing a branch with another user.

FAQ

How do I make a branch?

 git checkout -b <new_branch>

As noted above, make sure that your new branch name is prefaced with your user name, unless you intend to share this branch with other users.

It is important to note that when making a new branch, git will take all changes in your working directory and staging area with you. This is useful if you start a project, realize it is bigger than expected, and then decide to store these changes on a branch.

Ex:

> git checkout -b UserA-NewBranch

This will make a new branch that has the same state as the master branch.

Ex:

> git checkout 1b6d -b UserA-Old 

This will make a new branch that has the same state of the commit beginning with 1b6d.

How do I move between branches?

  git checkout <branch_name>

Note that git will try to take any changes in your working directory and staging area with you to the new branch. This can lead to conflicts that can be difficult to resolve; thus it is recommended that you commit all changes in your working directory (see: Committing Changes) before moving to a different branch.

How do I know which branch am I on?

 git branch

This command will list all the branches you have made. The branch you are currently on will be prefaced by a "*".

Ex.

> git branch
UserA-awesomeProject
UserA-coolProject    
* master

In this example the user is on the master branch.

How do I delete a branch?

To delete a branch you must not be on the branch. There are two ways of deleting:

 git branch -b <branch_name>

In this example the branch must be fully merged with the master branch

 git branch -B <branch_name> 

In this example, the branch is deleted regardless of merge properties

How do I commit only to the branch I am working on?

Commits work like they do currently, except you commit to a given branch instead of the master branch.

How do I push out my changes back onto the mainstream of development?

You will need to first merge changes from branch to master and then push from master to origin/master. Note that this will transfer your entire commit history on the branch to the master branch. It is recommended that you view your commit history before pushing your changes out to make sure you are pushing out everything that planned to push.

Ex:

> git checkout master
> git merge UserA-awesomeProject 
> git pull
> git push 

In this example the user first switches to the master branch. They then merge in the changes in the branch 'UserA-awesomeProject' into the master branch. They then push those changes out.

How do I keep my branch up to date?

You will first pull in the latest changes into the master branch and then merge these changes into the development branch.

Ex:

> git checkout master
> git pull
> git checkout UserA-awesomeProject
> git merge master

In this example the user first switches to the master branch in pulls in the latest changes from the shared repository. They then switch to their branch 'UserA-awesomeProject' and merge those latest changes with their branch.

How do I push my branch back to the main repository, so other people can work on my branch too?

First make sure that you are on your branch:

> git checkout UserA-awesomeProject

You might consider at this point doing a git merge master to bring the latest master changes into your branch, so the merging will be easier in the long run, but that is not strictly necessary. Next do a fully qualified push command to get your branch into the main repository:

> git push origin UserA-awesomeProject

What do I do if I'm in the middle of a project on another branch and I need to do quickly make some minor change to the main branch (master)?

You may use git stash to save your changes and reset your working directory to the tip of the branch that you are working on.

Ex:

> git stash
> git checkout master
> ... edit, test, commit, push on small change
> git checkout UserA-awesomeProject
> git stash apply
> ... continue to work on changes ...

In this example, the user is working on the branch "UserA-awesomeProject". They first stash their changes and then move to the master branch. They then make their minor change, go back to the UserA-awesomeProject branch and un-stash their working directory changes.

What do I do if I'm only part way through a project and need to stop? How do I make sure that I keep my work I have already done without making a commit that I don't want other's to see?

If you want to keep your changes, you will need to commit no matter what. However, what you can do is when you come back to your branch you can revert your last half-baked commit (Reverting changes) and then proceed as normal with your changes only existing in the working directory and/or staging area.

Other people prefer to keep their half-baked commits and work from there - either method is fine.