A quick and dirty guide to Git, msysgit and GitHub for Windows

A quick and dirty guide to Git, msysgit and GitHub for Windows

Summary

Introduction
Installing Git
Registering to Github
Generating an SSH keypair and register it to Github
Creating a project
Forking a project
Committing your changes and uploading them
Syncing with the master branch
Bonus
Conclusion
Some links

Introduction

After having struggled a lot to do the most basic actions with Git on my Windows 7 box, I decided that I would post a tiny guide to share my tiny experience and how I worked around the current flaws on Git for Windows.

At the time of this writing, MsysGit and Git are at version 1.7.2.3.

Installing Git

First, you have to install Git.

You can find several GUI tools like GitExtensions, GitSharp or TortoiseGit, but for me, only one worked : MsysGit. For a list of the Git tools for Windows, Wikipedia is your friend :
http://en.wikipedia.org/wiki/Git_%28software%29#Portability

MsysGit is the main port of Git for Windows, all the other tools are using it as a base. Unluckily, those tools seems to not be as much stable (although msysgit is not stable enough itself).

To download MsysGit :
http://code.google.com/p/msysgit/

Launch the setup, and continually press Next, the setup should set the best settings for your already. Don't forget to close your file manager prior installing, for the shell extensions to successfully register !

Registering to Github

If you want to use Github as your repository (that's the current repo of B3), it's now time to register an account :
https://github.com/signup/free

Generating an SSH keypair and register it

Now, for you to be able to communicate with Github securely (anyway Github will prevent you from connecting altogether if you have no key), you have to generate an ssh keypair, and then register it on the Github website.

1- Generating the ssh keypair
You've got 2 ways to do that : commandline or by GUI :
* commandline : Right-click in any folder, then click on Git Bash. Now in the terminal that opens up, type :

Code:

ssh-keygen -C "username@email.com" -t rsa

Supply your Github email address instead of this fake one. Accept the default location storage for the keys. When prompted for a passphrase, make up one, and don't forget it ! This is your private key, don't share it with anyone.

* by GUI : Right-click in any folder, then click on Git GUI.
Now go to the Help menu at the upper side of the window, then Show the SSH key. On the new window that shows (with an empty key), click on the button Generate a key. Follow the instructions, and you should now have a key of your own.

2- Registering the ssh keypair on Github
Now that you have a key, you must indicate to Github what it is, so that it can authenticate you.

To do that, login to your Github account, then go to Account Settings (next to the Logout link), then SSH Public Keys, and then Add another public key, and finally copy your public key (not the passphrase you made up, but the long key that was generated, you can show it again in the GUI with Show the SSH key).

Ok, now you've stepped over a big milestone ! You are soon finished.

Creating a project

If you want to work on an already existing project (like Big Brother Bot), you can skip to the next chapter.

Just right-click in a folder of your choice, and click on Git Init Here. The folder where you are now becomes the root of you project.

Now read on the rest of this tutorial to learn how to commit, push and pull changes.

Forking a project

If you want to make your own project, see the previous chapter Creating a project, and skip this one.

For this chapter, we will take the big brother bot dev branch as an example.

1- Making your own fork

First, login to your account in Github.

Then, visit the big brother bot dev branch, at :

http://github.com/xlr8or/big-brother-bot/

This is the main dev branch of Big brother bot. You cannot have a direct access to it, but you can fork it, meaning that you will duplicate this branch and create your own. Creating a fork has the advantage that it keeps tracking of the main and alternative branches, so that you can later branch back to any other branch.

To fork it, simply click on the Fork button that appears on the page linked above. That's it, you should now have your own fork of Big Brother Bot !

Now, you have to clone your fork, meaning that you will copy its content from Github to your own computer, locally.

To do that, on your fork page, select SSH (very important, in HTTP it didn't work for me) then copy the link that is shown, which should be in the format :

Code:

git@github.com:yourlogin/big-brother-bot.git

Then, go to the folder on your computer where you want to clone the datas, and right-click, then click :

- Git Gui for the GUI method, then click on Clone a repository.

* As the source, paste the SSH link that you copied just earlier.

* As target, browse to the local directory where you want to clone the datas (be careful : you must set a non-existent directory, so that Git can create it ; if the directory already exists, Git will refuse to do anything and you will get an error !).

When required, type your passphrase.

- Git Bash : if you want to do it directly from commandline (or if the Gui doesn't work, it can happen), type :

Code:

git clone git@github.com:yourlogin/big-brother-bot.git

This should do the trick. When required, type your passphrase.

Now there's one last thing to do : connect your fork to the original master branch so that you can later update your project with other contributors' changes

2- Connect with the main branch

To connect your fork to the main branch, right-click in the folder where you have set your fork, and click on Git Bash. Then, type these commands :

Code:

git remote add upstream http://github.com/xlr8or/big-brother-bot.git
git fetch upstream

Note : I advise to always take the HTTP url, not the Git one as it seems that the fetch and pull commands aren't working with Git read-only. So prefer to choose the HTTP url.

Issuing this command will not ask you for your private password as it only fetch the datas from the main branch, you cannot ever commit to it.

When everything is done, you should now have your own B3 fork on your computer ! You can now begin to code and contribute your own changes to the files Wink

Committing your changes and uploading them

For an pictured tutorial, see :
http://blog.lobberecht.com/2008/06/intro-to-windows-git-gui-in-pictures.html

Let's say that you have already edited some files, and you now want to upload your changes and make them available to everyone. The process here is not so straightforward, so I will divide it into 3 steps : selecting, committing (saving your changes) and pushing (uploading your changes) :

- Analyzing and selecting your commits :
Right-click in the root folder of your fork on your computer, then click on Git Gui.

You should now see a window with 4 panes :

In the Unstaged Changes, you should see all the files that you have edited, or added.
To add them in the waiting list of files to commit, select each file that you want to commit, and click in the menu Commit > Stage to commit. The selected files should be moved to the pane named Staged Changes (Will Commit).

- Committing your changes :
Now that your files are ready to committed, you should describe what your changes are about.
To do this, enter a text in the field named Initial Commit Message at the right-bottom corner of the window. This will help other devs (and the master dev) to accept your changes and merge them in their own branches.

When you're done, simply click on the Sign Off button, then click on the Commit button. This will save the changes locally. These changes will NOT be reflected online, and are not yet accessible to other users, only to you.

You can now repeat these 2 steps several times, and when you are ready and satisfied with your commits, proceed to the Push step.

- Pushing your changes :
Last step is to upload your changes online, on Github, and make them available publicly to everyone. To do that, simply click on the Push button, or in the Remote menu, click on Push.

Or with Git Bash commandline :

Code:

git push origin master

You can now visit your fork webpage on Github to check if your changes are now effective online.

If everything worked well, then congrats, you have just done your first contribution !

Syncing with the master branch

Time has passed, and there are now changes in the other branches that you don't have. To sync your fork with the master branch, simply type in the Git Bash :

Code:

git fetch upstream
git merge upstream/master

Or alternatively :

Code:

git pull upstream master

Wait for some time, and your local fork AND remote Github fork should now be up-to-date with the latest changes from the main master branch !

(optional) If Git refuses to sync you because you have changes uncommitted ("Please, commit your changes or stash them before you can merge"), then you can quickly drop them by issuing in the Git Bash :

Code:

git stash

This will save your uncommitted changes in a 'backup' directory, and will clean your current working directory, so that you can now sync yourself with the above commands.

If you later ever want to get back your uncommitted changes you stashed, just :

Code:

git stash list
git stash show <id_of_the_stashed_commit>

And to restore one :

Code:

git stash apply <id_of_the_stashed_commit>

More infos about git stash : http://www.kernel.org/pub/software/scm/git/docs/git-stash.html

Bonus

How to get a preview of the changed files ?

For that, you can use TortoiseGit, this will add a mark on your files depending on their status (synced, changed, conflict, etc...).

What's the use of the Sign Off button ?

The sign-off button simply adds a signature to your commits, authenticating yourself as the author of this patch. This mainly for legal purpose, as it permits to avoid the inclusion of copyrighted materials into opensource project (since you certify by signing off that, to the best of your knowledge, the material you include is opensource and abide by a similar license to the project). This ensures a way to chain back to where unappropriate materials were included.

This is mainly used for the Linux kernel, but it is a good practice to use it.

From http://stackoverflow.com/questions/1962094/sign-off-feature-in-git-is-for-what :

Quote

Sign-off is a requirement for getting patches into the Linux kernel and a few other projects, but most projects don't actually use it.

It was introduced in the wake of the SCO lawsuit, (and other accusations of copyright infringement from SCO, most of which they never actually took to court), as a Developers Certificate of Origin. It is used to say that you certify that you have created the patch in question, or that you certify that to the best of your knowledge, it was created under an appropriate open-source license, or that it has been provided to you by someone else under those terms. This can help establish a chain of people who take responsibility for the copyright status of the code in question, to help ensure that copyrighted code not released under an appropriate free software (open source) license is not included in the kernel.

Conclusion

Despite the definately ironic tone I used in this tutorial, I don't dislike Git. I find it to be a very efficient revision control system, even more when combined with Github. It's just that the support for Windows is still very poor, and I hope that it will change in the future. For now, by following these guidelines, you should be able to do the basic necessary actions.

Some links

Some other very good tutorials that inspired me :
http://kylecordes.com/2008/git-windows-go
http://help.github.com/forking/
http://blog.lobberecht.com/2008/06/intro-to-windows-git-gui-in-pictures.html

Have fun and happy coding !
GrosBedo