Git Tutorial Part 1: Working with branches and release versions of your Rails app

This week I am working with branches in git for the first time.  Up until now I just used my master branch for everything which works ok since I am the only developer on most of my apps, but now I realize branches will make my life alot easier in more than a few situations.  I am working with my brother on a project where it is necessary for us to use branches, so he started me on the path to git branch knowledge.  Here is my workflow so far.. and most of this relates to working with a Ruby on Rails web app that has stable milestone releases and a master branch for the future version.

I guess lets start with the basics of initializing git and using Github to host your code.  I am assuming you have git installed and you are using Github to host your main repository.. if no, proceed to Google.  Also, I am assuming you already have a project.. Rails or other.

ONE BIG NOTE: REALIZE THAT JUST BECAUSE YOU CREATE A BRANCH OR MAKE A CHANGE AND COMMIT IT ON YOUR LOCAL MACHINE, THAT DOES NOT MEAN THAT IT SENDS IT TO GITHUB OR THE MAIN REPOSITORY!!!  I WAS TOTALLY CONFUSED ABOUT THAT THE FIRST TIME I USED GIT.  LEARN TO PUSH AND PULL!

Go to your project directory, initialize git, add all the files and then make your first local commit with a message

1 cd /your_app
2 git init
3 git add *
4 git commit -m 'initial commit'

Now you are set up with your local repo. Next you need to login to (or create) your github account. You will create a new repository and name it the same thing as your local app. They will give you instructions similar to what I am telling you here after it is set up. This will add an origin to your local git config and then push all the local files that you just committed to that origin. If you have problems getting this to work, take a look in the github help about security and setting up your ssh keys here

1 git remote add origin git@github.com:your_username/your_app.git
2 git push origin master

You will get the following output

Counting objects: 22, done.
Delta compression using up to 2 threads.
Compressing objects: 100% (19/19), done.
Writing objects: 100% (22/22), 3.73 KiB, done.
Total 22 (delta 3), reused 0 (delta 0)
To git@github.com:your_username/your_app.git
* [new branch] master -> master

What you see here is that your files were transferred to github and a new branch was created called “master”. The new branch was created automatically since there were no branches in this github project. To see what branches you have available on your local machine type:

1 git branch
* master

Your local machine knows about one branch and it is called master. Lets do some more branching now. My project is already at Version 1.0 but I am just now adding it to Github. Version 1.0 is stable and I may or may not make fixes or small additions to it. I am planning out my development roadmap and some major changes are going to happen in V2. So I don’t want to have to worry about changing and adding a bunch of crap and then realize that I need a minor fix on V1.. that would be a mess because I would have a codebase that was moving toward V2 and I would have to hack and hack in order to deploy that small change back to version 1.. what a mess. Thats where branching comes in. We need a Version 2 branch so we can keep things separate. To create another branch on your local machine do this:

1 git branch version-1_0-stable

Lets see if it worked..

1 git branch

OUTPUT:

* master
  version-1_0-stable

Yep.. there is our new branch. But notice that we are still on the master branch. Git puts a asterisks beside the current branch. In order to switch branches on our local machine, we need to use the checkout command.

1 git checkout version-1_0-stable

OUTPUT:

1 Switched to branch 'version-1_0-stable'

If you run “git branch” again, you will see a star beside version-1_0-stable. Wouldn’t it be easier if you could branch and switch all in one command? Oh yeah.. you can. Why didn’t I just say that in the first place?? Who knows, why I do alot of stuff… Here is how you delete your branch and then create it with the one-liner. Note that you can’t delete a branch you are currently on, so you must checkout back to master first:

1 git checkout master
2 git branch -D version-1_0-stable
3 git checkout -b version-1_0-stable

By throwing in that -b flag, you are telling git to create the branch and then switch to it all in one move.

Ok, cool, so I got another local branch. Why don’t I see the new branch in Github?? Because I have been working with git branches locally. Github is not aware of these changes because I have not pushed anything to it. You can see what github has by logging in and clicking on the “Switch Branches” dropdown in your project or by using the -r flag on your local box -> “git branch -r”. So now we need to tell Github about this branch.

1 git push origin version-1_0-stable

OUTPUT:

Total 0 (delta 0), reused 0 (delta 0)
To git@github.com:your_username/your_app.git
 * [new branch]      version-1_0-stable -> version-1_0-stable

Frickin awesome dude… I gots a new branch and github has it too. So I have 2 branches that I can work in separately. Most of my work will be in the master branch which is on the path to version 2, but if something craps out in V1 and I have to put in a bug fix, I just “git checkout version-1_0-stable”, make my changes, commit them, and push them to the the V1 branch. Then I could easily deploy the new code without worry about V2 code getting in the way. Lets try that out:

You are already using version-1_0-stable. So go to your editor of choice and change a file. You must commit the changes locally first. This will commit to only the current branch, so master will not get these changes since you are on version-1_0-stable. You can commit your files several ways. Here are the 2 ways I do it.
1. Commit all local changes at the same time and use -v to view the changes

1 git commit -a -v

2. Commit a single file if you have other outstanding changes that you don’t want committed yet. Just use the relative path to a single file (or * wildcard it for a whole dir).

1 git commit -v path/to/your/file

Now your local machine knows about the committed files, but not Github. You have to push.

1 git push

OUTPUT:

warning: You did not specify any refspecs to push, and the current remote
warning: has not configured any push refspecs. The default action in this
warning: case is to push all matching refspecs, that is, all branches
warning: that exist both locally and remotely will be updated.  This may
warning: not necessarily be what you want to happen.
warning:
warning: You can specify what action you want to take in this case, and
warning: avoid seeing this message again, by configuring 'push.default' to:
warning:   'nothing'  : Do not push anything
warning:   'matching' : Push all matching branches (default)
warning:   'tracking' : Push the current branch to whatever it is tracking
warning:   'current'  : Push the current branch
Counting objects: 14, done.
Delta compression using up to 2 threads.
Compressing objects: 100% (7/7), done.
Writing objects: 100% (9/9), 815 bytes, done.
Total 9 (delta 5), reused 0 (delta 0)
To git@github.com:your_username/your_app.git
   d8b9507..862d326  version-1_0-stable -> version-1_0-stable

Look at all those warnings. WTF is git talking about?? They want us to type more options in?? Well.. I actually think this is crap, but there is probably a good reason behind the default behavior. By default it is going to push all branches that it finds on your local box over to the origin server. So for instance, if you change and commit something on master, switch branches to V1 and change and commit something on that branch too, then git will push both of them. That could potentially be dangerous if you were not ready to push master or V1. So in order to fix that you need to pass your git config some options to make it only push the current branch you are working in.

1 git config push.default current

If you look at /your_app/.git/config, then you will see it added some options to your config.

[push]
        default = current

Next time you issue the git push command the warning goes away and it only pushes the current branch. Thanks for not being an asshole this time git… I really appreciate it.

So we are looking pretty good, but there is one more thing that is bugging me. What if I make a change to V1 and I want the changes to show up in V2 also. The bug is most likely in V2, unless I removed that feature or completely re-coded it. So how do I get them darn changes over to me other branch?? Move back to master (V2), maybe check the differences so you don’t totally mess it up, and then issue the merge command:

1 git checkout master
2 git diff master version-1_0-stable
3 git merge version-1_0-stable

If you have any conflicts, the merge might not work and it will tell you to fix them. Here is the message “Automatic merge failed; fix conflicts and then commit the result.” So how do I fix the conflicts? Go to the files that it marked as conflicting. In my case, my LICENSE file was conflicted so it said:

Auto-merging LICENSE
CONFLICT (content): Merge conflict in LICENSE

So I look at the file and git has put some junk in there that shows where the conflicts are and which branch they are coming from. Just edit the file to make it work and get rid of the junk (<<<<<<<<<<).

<<<<<<< HEAD:LICENSE Copyright (c) 2010 John McAliley  ======= Copyright (c) 2009 John McAliley >>>>>>> version-1_0-stable:LICENSE

Hmm.. its 2010, the file should say that, so I edit and make it look like this:

Copyright (c) 2010 John McAliley

Then I do a “git commit -a” and the conflict has been resolved. If you issue a “git merge version-1_0-stable” then it will tell you its up to date. Cool, I guess we are done. Not so fast chief!!! Don’t forget to push it to Github

1 git push

Now we done! The change in V1 is also in V2. Go drink a beer. You deserve it.

I think that about covers my workflow as it stands now aside from pulling using the rebase command. Yehuda Katz has an excellent tutorial on his Git workflow regarding pulling, pushing and resolving conflicts (although he does not go into branching). I have only been doing branching and versioning in git for a week, so I am sure some of you git masters might have a better workflow. If so, don’t be stingy.. leave a comment and show people a better way. Next tutorial will cover tagging as related to minor version changes in the master before it is actually considered stable. Check out the ruby on rails source in github if you can’t wait. They use branches and tagging for major and minor releases (including betas in the master branch)

Advertisements

Share your thoughts with us!!!

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s