Monday, October 13, 2014

Getting Started with Git on Windows

I'm gonna assume you have a day job and you need to get Git working on a new machine and/or a new repo, i.e. where the point of the exercise is either to (A) back up your code into the cloud, possibly for sharing; or (B) download a repo that someone else has already created (e.g. your coworkers) and start working with it. I'm writing this post because I find myself going through the following steps every 4-6 months and frustrated trying to pull together all the crap I need, especially when I get dumb errors like the ubiquitous "permission denied (publickey)". If that's you, this guide should help.

Further, these instructions are for the Git Bash / Git GUI set of tools. At home I'm using Source Tree, so some of this stuff is similar, and if that's what you're doing there's some clues below that might help with errors you get.

BTW, another common case (let's call it C) is to use Git with an op*n-source project but there's tons of samples out there for getting involved in op*n source -- in which case you're usually forking an existing repo and doing an entirely separate code-submission thing, so I leave that to other people to explain.



LETS GET STARTED

1. Get GitBash and GitGUI from github. The windows command prompt is ... a dodgy thing. I much prefer using bash, party because you get cool Unix tools in the bundle.

2. Open up GitBash. Set your name and email (btw the $ is just an indicator that this should be done at the bash shell prompt).
$ git config --global user.name "Your Name"
$ git config --global user.email "your@email.com"
3. If you have a new, unversioned project and want to create an online repo for it, eg to back it up to GitHub or Bitbucket or Codebase or wherever, you need to create a new local repo; that's the way Git works. Move (cd) into the root directory of the project's folder hierarchy, and run:
$ git init
4. If you don't have an account with the online repo, go do that. If it's your company's repo, you'll have to talk to your IT team to find out how to do this.

5A. Next you need a public/private key pair. If you're using a Windows-based gui client other than Git GUI take a look at step 5B below.

Fire up GitBash and generate a key:
  1. $ ssh-keygen -t rsa -C "my@email.com Oct 2014". That last bit is a comment, put whatever you want, but I find these two bits handy for remembering which key is what. The default bit length is 2048 bits (add e.g. -b 1024 to change this), and the -t rsa is, actually, the default: RSA for use with SSH protocol version 2.
  2. You might need to start the SSH agent: $ ssh-agent -s
  3. Add your key to the agent: $ ssh-add  
  4. Copy the public key to your clipboard: $ clip < ~/.ssh/id_rsa.pub 
  5. Go into your online repo's account settings page and add a new SSH key, pasting in the info you just copied.
NOTE: if you created a key using PuTTYgen you'll need to export it in SSH format to use with bash!

5B. If you're using a Windows-based Git client, you'll need PuTTY to be your SSH agent. (Note that Source Tree installs the putty tools; if you're using Source Tree you don't need to bother with the separate download and install; check out their FAQ) Here's the home page for PuTTy; you'll probably want the zip file or installer, as it includes puttygen and pageant. I think the installer has an option for starting pageant (the SSH agent for the PuTTY suite) when you log in, which will probably be useful. Once you've got putty downloaded, here's how to generate a key:
  1. Run PuTTYgen
  2. Enter a useful comment here. I use the date and which repo/system I plan to use the key for, eg "[workplace] Oct 2014" or "my@email.com Oct 2014 2048bit rsa".
  3. Hit Generate
  4. Move the mouse around a bunch
  5. Save the private key. If you lose this... eh, you'll have to go through these steps again. However, if someone ELSE gets it, they can pretend to be you and eff up your repo. Not advised.
  6. Save the public key; chances are you're gonna have to use it several times when trying to debug a repo connection that's misbehaving.
  7. Copy the "Public key for pasting" stuff from PuTTYgen. You can probably close PuttyGen now.
  8. Go into your online repo's account settings page and add a new SSH key, pasting in the info you just copied.
Next time you reboot your machine, if you get authentication errors, it could be because you're not running pageant and/or it doesn't have your key loaded.

6. If you're going to be working from an existing repo (eg you just got hired or got a new machine and are going to start working on an existing codebase), then you need to "clone" the repo. GUIs have their own commands for this. From a Bash shell, use:
$ git clone ssh://myusername@sourcehost.com:port/RepoName.git
This will create a folder named RepoName in the current directory. That is, there's no need to create the repo folder yourself.

7. If you've got source code already and now want to upload it to a fresh repo up there in the cloud, GUIs have their own command. But let's say you did the 'git init' up above. How to add this to your Bitbucket/GitHub/etc account?

.... tbd, because I haven't done this yet. I actually did it the other way: created a repo in the cloud, cloned it local, then copied my source code in.