Home | Tutorials | Using GitHub with Windows

Using GitHub with Windows
by Nate | April 18, 2010 | 4 comments Skill Level: Beginner

---

GitHub

All I want to do is work on hardware and code, and work with other people to make it better.

GitHub is a place where files (code, PCB layouts, images) can be submitted and then shared with people. I throw it up on GitHub, you download it to your computer, makes changes, then push it back up to GitHub. As the group makes changes to the files, we need a system to keep track of all the changes (versions). GitHub is a place that allows for easy version control.

If it's a really active project, multiple people join forces to create code revisions, patches, and in general make the world a better place. GitHub is one of many sites that offer code subversioning services. I picked GitHub because of some friends recommendations. I've grown to really like it for simple, individual projects, but it did not come easily when first starting out. I wrote this tutorial to get you through the basics of downloading a GitHub project, and then creating your own project.

While this all sounded great, I got increasingly frustrated with the tutorials on how to actually use GitHub. As a windows user (I'm apologize to all you Linux users, you guys are light years ahead of me!), I don't know what a bash prompt is. Why can't I login to GitHub and get the files I need? Unfortunately it's not quite that simple.

This tutorial is written to show folks how to use GitHub and TortoiseGit with Windows (specifically Windows XP). I will never ask you to go to a bash prompt. I am not an expert. I barely know the basics to get code up and down. Please recommend changes where needed.

 

---

 

Pulling down a GitHub project

This tutorial will show you how to setup a Windows machine to pull down a GitHub project, make some changes, then submit it back to the main project. I use this process for OpenLog and it has worked very well so far.

Before you do anything, you'll need to download these programs:

• TortoiseGit : The version I am working with is 1.4.4.0 (1.5.2.0 also works)
• msysgit : The version I am working with is 1.7.0.2

During the installation of both msysgit and TortoiseGit, I chose all the defaults. You will need to reboot your computer so that it can complete installation. See you in a minute (or five)!

And we're back! After installing TortoiseGit, you won't see any new icons really.

There is no 'TortoiseGit' program to start. Instead, you'll see new options in the menu when you right click on stuff. Namely, when you right click on a folder or directory. So open up windows explorer and create a directory called something like 'C:\temp'. Now right click on 'temp' - you should see the a menu pop up:

Step 1) Checkout the new Git Clone, Git Create repository here, and TortoiseGit options in the menu. These are our new tools! Click on 'Git Create repository here'.

This will tell Git that we want this directory to be version tracked. We're essentially preparing (initializing) this directory to handle a GitHub project.

Now go back to that 'temp' directory and right click again. The TortoiseGit options have changed slightly because it sees that this is a version controlled directory.

Trick: If you ever want to make TortoiseGit to stop mucking with a directory, simply delete the .git hidden folder.

Step 2) Now if you highlight 'TortoiseGit' with your mouse pointer, you will see a very large tool menu open up. Here's where the magic happens. I've got some ulterior motives here (getting people to help me with OpenLog) so for this example, click on 'Pull'.

Note: If you do not see 'Pull', then you are like me on a 64-bit Windows 7 system with 1.5.2.0 of TortoiseGit installed. You will need to hold the 'shift' key while you right click on the folder.

Step 3) You should now see a window like this. We are now asking TortoiseGit to go out and fetch a project. Click on 'Arbitrary URL:' and enter

git://github.com/nseidle/OpenLog.git

Then click on 'ok'.

TortoiseGit went out to GitHub and pulled down some files.

TortoiseGit now gives us this cryptic window. What is this? This window shows you what files have changed since you last checked out this project. Since this is your first time, click on the upper 'RefBrowse' button and select 'Log'

Here you can see what was changed in each file. You can also see the notes from each author. When downloading new versions it's and good idea (and extremely helpful!) to know what changes were made and why. Close both those windows and let's look back at the 'C:\temp' directory:

It's full of files! Congratulations, you've pulled down your first project from GitHub! In the case of OpenLog, here you see the Eagle files, some images, and the 'Code' directory. You can then poke around. Please help us with OpenLog suggesting improvements or issues.

So when pulling down an existing GitHub project, here are the steps:

• Create a new local directory
• Right click on that directory and create a new repository
• Right click on that directory and do a 'pull'
• Enter the GitHub location of the project and click ok
• Read the change log

 

---

 

Creating your own GitHub project

This is fun and all, but what if I want to create my own GitHub project? That gets more complicated.

I find GitHub is very good for version control. When you submit files you can keep track of why you made the changes and are able to view the differences between your code and what someone else has submitted (GitHub has a built-in 'diff' function). GitHub is not so good at handling hardware files such as binary files (like Eagle or PDFs). But that's ok. It's still very valuable to be able to go back in history and see why we went from version 1 of OpenLog.brd to version 1.5 of OpenLog.brd and the changes and comments along the way.

Do not worry about the field labeled 'SSH Public Key'.

To create your own GitHub project, you'll first need to create a GitHub account. Just hit GitHub.com/plans. Pick the plan that works for you. SparkFun pays for its GitHub account, but the free version is quite acceptable for most open source hardware projects. Do not worry about the field labeled 'SSH Public Key'. Click on 'I agree' and enter in the various user name and password boxes.

Yay! You're in. Let's create a new repository. Click on the 'New Repository' button and enter the project name, description, homepage, simple stuff. I created a project called 'Tutorial'. Now let's go back to the Windows file explorer. Create a directory, name it whatever you want - "C:\tutorial" is what I used. Right click on the folder and 'Create' a repository in the tutorial directory (see Step 1 above for more info). Now before we do anything to this directory, we need to pull down the contents our current project sitting on GitHub.

Right click on the 'C:\tutorial' folder, highlight TortoiseGit, then 'Pull'. You will need to give the arbitrary address of your GitHub project. For me and this tutorial, it was:

git@github.com:SparkFun-Tutorial/Tutorial.git

But your link will be different!

You will probably see this error: Disconnected: No supported authentication methods available. This means that you haven't loaded your authentication keys. You have to get a key setup with GitHub so that they know who you are.

Everytime you talk to GitHub (by pushing files to them), GitHub will check to make sure you are who you say you are. They do this very securely using SSH keys. The private key sits on your computer. The public key is given to GitHub. Thankfully, you only have to do this once. Time to generate a private SSH key!

Click on Start->Programs->TortoiseGit->PuttyGen. Then click on the 'Generate' button and wiggle the mouse over the green bar. This will generate a random key. Save this key as a private key by (you guessed it) 'Save private key'. Save the key to a place that you can remember (something like 'C:\git-keys') but safe (on your local machine, not on a public computer or network). You might want to assign a passphrase before saving the key (I didn't but I'm a bad security example)... You should now have a private SSH key saved somewhere on your local machine. Don't close the window!

Before you close this window you will need to copy the public key. This is the text within the 'Public key' box. Select all the text in that box, right click, and hit 'Copy'. Now let's go back to GitHub to let them know what our public key is:

From GitHub, click on 'Account Settings'. Oh hi blinking red text! I see I need to give you my public SSH key. I have that! Paste the full text into the GitHub SSH Public Key box, add a title, and click 'Add Key'. You should be set. If you haven't yet, you can close the PuTTy Key Generator.

Now you really should add information like your name, email, any websites, and a profile icon to your GitHub account. A profile icon goes a long way when people are viewing your project - it will show that you are dedicated and serious about your project. No profile icon = not serious.

Now click Start->Programs->TortoiseGit->Pageant. Nothing happened... But wait, there's a new icon in the task bar! It looks like a computer with a hat on - that's Putty agent lurking in the background.

Right click on that guy and select 'View Keys'. Click on 'Add Key'. Navigate to the key you just saved. You will be asked for a passphrase if you added one. Pageant now has your private key loaded and you are ready to rock with GitHub!

Now go back to the tutorial directory. Within that directory, stick a file, any file. I created a quick text file but you could easily do c files, PDFs, images, anything.

Now right click on that file and click TortoiseGit->Add

Yep, that's the file I want to add. Click ok.

There is now very angry '!' on my file. That means that the file has not be settled with the repository (GitHub in this case). To really add this file to the repository we have to commit the changes, then push the changes. I know, a lot of steps, but they'll make sense down the road.

Right click on the 'tutorial' directory and select Git Commit -> "master". This is where you tell the world (and yourself) why you want to add this file to the repository. Pretty simple but don't skip it. You'll be surprised how beneficial these little notes are down the road as you try to recreate what you were thinking that night at 1:30 in the morning... Click ok. Click ok again (TortoiseGit is just confirming the add).

Congratulations! The icon is now green and happy. You've successfully committed the file to your local repository but you have not pushed it live to the world (GitHub) yet. To do that, you need to right click on 'tutorial' directory->TortoiseGit->Push.

You will need to fill in the 'Arbitrary URL' with your project's Read+Write URL. Mine was git@github.com:SparkFun-Tutorial/Tutorial.git but remember, your project and URL will be different.

Bomb diggity.

Now when we return to GitHub and hit F5 to refresh the page.. Hey hey! That's the file I was working on! Congrats! You are now able to push files to GitHub.

Whenever working on a project I recommend the doing the following at the start of each coding day:

• Load Pageant
• Add your private key
• Create an empty/new directory
• Create a Git Repository in that empty/new directory
• Do a Pull to that empty/new directory

You should now have all the files in that directory. Edit like crazy, test, make sure everything works. Once you're ready to push this new fancy version:

• Right click on directory and commit (this commits all the changes you've made to your local repository)
• Add a lot of comments to say what changed and why you're committing these changes
• Right click on directory and push to GitHub (this makes the local repository live to the world)

But hey, why in the world is GitHub identifying me as an 'unknown (author)' when it's me! This was a really annoying 'bug' with GitHub. I'm logged in, I've got my keys loaded. It's me! Really! Why does GitHub not identify me? The problem is that GitHub didn't get your name and email when you submitted your files. So silly, but easy to fix:

This is a really small and random error. You need to set your name and email address correctly in the TortoiseGit settings.

Once you have your email inputted correctly, your commits to GitHub will show up normally.

That's it! I hope you enjoy using GitHub. Once you push and pull some files, I recommend you check the Issues tab. This is a really easy to use system to keep track of all the things I need to do to my code. A good example of my AVC rover:

• Add ability to manually edit a given waypoint
• Add ability to start navigation from an arbitrary waypoint
• etc.

Each one of these could be an issue. You can then sort and prioritize the issues and knock them off as you solve them.

The Wiki is also super helpful if you're creating a collaborative project such as OpenLog. The Wiki is quickly and easily edited to add basic text, links, pictures. This allows you to create a work-in-progress datasheet. Remember, if it's not documented, it's not nearly done. I find Textile (what GitHub uses for wiki text input) to be a good balance of easy to use markups and features. Well done GitHub. And thank you TortoiseGit - you make us Windows users very happy.

I hope this helps you with your next code subversion project under Windows!

-Nathan