Difference between revisions of "Git Guide"

Revision as of 15:52, 29 April 2011

Introduction

Git is a distributed version control system that lets you manage from small to very large projects. You can see a Subversion comparison in the official Git wiki.

This howto will guide you through the setup process of git Github and the usage of SSH keys to work with git. Github is a web based service to store public and private git repositories. Funtoo's portage tree and overlays are github based.

Setup

Recommended packages

Before you start configuring git we recommend that you have installed keychain on your system to manage the SSH keys. So just type emerge -avt keychain as root.

Backing up existing keys

For security reasons you will backup your existing keys in ~/.ssh. It can be possible that your .ssh directory is empty, so this will just result in an error message.

~ $ cd ~/.ssh
~/.ssh $ install -d backup-keys
~/.ssh $ cp . backup-key/ .

Generating a SSH key

Now you need to generate a new key for using with your Github account:

~/.ssh $ ssh-keygen -t rsa -C your@account.com

Where you replace your@account.com with your e-mail account that you like to use on Github. You can use multiple SSH keys but not with the same e-mail address. If you use multiple accounts, we recommend to use your user and your hostname, for example user: funtoo on host: funtoo: ssh-keygen -t rsa -C funtoo@funtoo.

This will ask you where to save the file with a default name id_rsa. If a file exists it will not ask us to overwrite it, so save it for example as github-ssh-key or user@hostname, where you replace user with your username and hostname with your hostname. It will ask you for a password. For that git-key we stay with a password-less key, so you can easily interact with github. Anyway if you feel more comfortable with a password add it here.

You can see a extended explanation of this process in generating a key pair at Keychain wiki entry.

Loading the new SSH key

You have now two options to load the new ssh key for git: manually or automatically. In both cases we will use keychain to do it.

Manually

~/.ssh $ keychain --inherit --eval --agents ssh your-ssh-key-name

Where your-ssh-key-name is the SSH key you generated above.

Automatically

To load the keys automatically we need to edit your .bash_profile that will start a background process with the indicated ssh keys. So edit that file with your editor of choose:

~/.ssh $ cd ..
~ $ vim .bash_profile

or

~/.ssh $ cd ..
~ $ nano -w .bash_profile

And add at the bottom of the file a new line with the following content:

eval `keychain --eval --agents ssh your-ssh-key-name`

Where your-ssh-key-name is the SSH key you generated above. your-ssh-key-name could also be a list of keys like key1 key2 ... keyn, what would mean that keychain loads all this keys to one ssh-agent and not starting several subprocesses for it.

Exit with CTRL + X and save with yes for nano or Esc and :wq! for vim.

Now you need to reload the profile to load the key:

~ $ source .bash_profile

* keychain 2.7.1 ~ http://www.funtoo.org
* Starting ssh-agent...
* Adding 1 ssh key(s): /home/username/.ssh/your-ssh-key-name
* ssh-add: Identities added: /home/username/.ssh/your-ssh-key-name

~ $

Configuring Github

For using Github we need some basic configuration:

~ $ git config --global user.name "Real Name"
~ $ git config --global user.email "your@account.com"

Where Real Name will be the name displayed on commits and your@account.com the e-mail account (or user@hostname) you used to generate a SSH key for.

Next you need to add the SSH public key to Github so they can recognize your SSH key. This has to be done by their website. Login with your user or create a new one and navigate to: Account Setting > Click SSH Public Key > Click Add another public key. Add a title and the output of your-ssh-key-name.pub that you can be seen with cat ~/.ssh/our-ssh-key-name.pub and save it.

Finally navigate to Account Settings > Account Admin and look for your **API Token**. Copy it and add it to your github config with:

~ $ pre git config --global github.token your-token-here

Where your-token-here is your **API Token**.