Working with branches in Git
Introduction
Why use branches
Branches help separate different projects so that it is easy to push out only finished projects. Branches also tend to be easier than cloned directories for pulling in changes and for sharing 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.
Branches also have the added benefit that users can share a development branch and so work together on a project without disturbing the master branch (which is something we have occasion to do on our project frequently).
And keep in mind, ease of branching was one of the reasons we chose git over other source code control systems.
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 -b UserA-Old someOtherBranch
This will make a new branch that has the same state as someOtherBranch.
Ex:
git checkout -b UserA-Old 1b6d
This will make a 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 "*".
Example output:
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 that branch. There are two ways of deleting:
git branch -d <branch_name>
In the above example the branch must be fully merged with the master branch
git branch -D <branch_name>
In the above 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. All that is necessary to ensure that a commit is only recorded for one branch is to make that commit while you are on that branch.
How do I push out my changes back into the main development branch (master)?
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 only pushing out changes related to your intended project.
Ex:
git checkout master git pull git merge UserA-awesomeProject git pull # if needed 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.
In order to share your branch with other users you will need to push your development branch to the main repository. This will allow everyone access to this branch, after they do a 'git pull'. This is different from the question above since you are sharing your branch with other users before merging these changes in the master branch.
First make sure that you are on your branch:
git checkout UserA-awesomeProject
Next do a qualified push command to get your branch into the main repository:
git push origin UserA-awesomeProject
It is recommended, but not necessary, that you merge in changes from the master branch before pushing to the main repository since this will make future merges easier (see Keeping up to date).
Note that there is potential for tag name conflicts between shared repo tags like this and your regular private tags. Try to choose a reasonable descriptive and unique name. We may need to develop additional conventions for shared-tag names such as prefixes like bug_ or feature_ being required.
Once shared tags go out to the shared repository, they are essentially un-deletable. Once the tag has been seen by everybody, it can exist forever.
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 and pulls in the latest changes from the shared repository. They then switch to their branch 'UserA-awesomeProject' and merges those latest changes with their branch.
What do I do if I'm in the middle of a project on another branch and I need to 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 pop # 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 part way through a project and need to stop? How do I make sure that I keep my work without making a commit that I don't want others 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.
