Basic instructions for git / GitHub

So, git is a version control system, and GitHub is a popular host for git. I don't know why it's so popular, but it may be because it makes it promotes forking and merging. If I want to extend or fix a bug in a publicly hosted project (e.g., jquery, Play framework, node), I can easily fork it and modify it at will. I can then submit (or not) my modifications to the owner of the original repository.

On a recent project, I finally decided to give it a try. I signed in at GitHub and installed its Windows client, which provides the basics: create local repository, create branches, commit, and publish/sync. After creating a local repository, I moved my files to the repository folder created at the git's deafult folder, went back to the client, commited it and published. That's it.

I found the dynamics quite interesting. I change my files, as usual. Then, anytime I want, I go to the client, which lists the modified files with the diff. Then I commit these files, describing what has changed. This is all local, and I can sync with the server anytime.

However, there were two other things I wanted to get done: to create a release and to publish it live (as it is an web project). This is not supported by the Windows client as of now, and it's not quite obvious to find out, so this is how I've done it:

How to create a release with GitHub Windows client

This can be done with the tagging mechanism. Once you create a tag, all its files are available as a single .zipped file. So, after commiting everything you want, you will need to open a command shell and add a tag refering to that commit.

In the client system, go to the repository, select the branch (if you haven't created a branch yet it will be in the default 'master' branch), then click on 'tools' / 'open a shell here'.

To find out the ID of the commit, use the git log command:

$ git log
or, for a brief version (preferred way):

$ git log --pretty=oneline

this will list all commits of this branch. In my case, it was this:


50b2ab641937cfcd9792923fa7bc47a40d6e51d0 balancing the difficulty
4edcda321423bece568e055b902e5d68d51251fe first commit

where the first collumn is the ID and the second collumn is the description of the commit. Then, you just need to use the git tag command, like this:

$ git tag -a 'tagName' 'commitId'

No, you don't need to tipe the entire Id, the first chars will suffice. For me, it was this:

$ git tag -a v1.0 50b2ab

It opens a text file - write the tag description, save it and close it. Now your release 1.0 is created. However, only in the local repository, you still need to send it to the server:


$ git push --tags

Ok, now you're done! Go to your GitHub page ( https://github.com/username ) and see that your release is right there in the tags' tab, with the option to download it as .zip and as .tar.gz

This was done based on the GitHub Learn site. I know, it is not as easy as it should be, but you probably won't be doing this often, anyhow.

The git tag command, without arguments, will list all tags you created so far:

$ git tag

The same can be achieved with

$ git describe --tags

No, I don't know what's the difference. Anyway, you may also delete your tags.

So, summing up:

$ git log --pretty=oneline
$ git tag -a 'tagName' 'commitId'
$ git push --tags

How to host your web project at GitHub

GitHub provides the feature of creating static pages for your project, on the likes of Google Sites, as well as a wiki. A third alternative is to create your own website, either for your user as a whole or for a particular project/repository.

To create a site for your GitHub project, open it in the GitHub client, create a new branch named 'gh-pages' and publish it. It will be available at http://username.github.com/repositoryName

Since my project was an web project, which was the actual site I wanted to get deployed, instead of creating a new branch I just used my 'master' branch. To do this, go to your repository in the Windows client, click on the branch name (at the top of the windows), then click 'MANAGE'. Then, click on the plus icon of the branch that you will use and type in 'gh-pages'. The plus icon reads "Create a new branch using this branch as the starting point".

After that, you can point to http://username.github.com/repositoryName and see your web system up and running. Actually, it may take a for it to be created, in the meantime GitHub will show a 404 error page.

So, summing up (2)

1. Create a 'gh-pages' branch in your repository
2. Access it at http://username.github.com/repositoryName

Points to explore later

• Git in Eclipse
• Gists
• Defining a proper workflow
• Markdown (readme.md)
• Working with different branches and forks

And what about requirements?

The GitHub client is far, FAR from complete. However, it does provide the basic and most used functionalities with a good usability and a great response time. It does help its users. This is a lesson on requirements prioritization and release planning ;)