Git Guide

Please be aware that this text needs to be revisioned and read to be corrected.

Please be aware that this text needs to be revisioned and read to be corrected.

Introduction

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

This how to will guide you to setup git working with Github using SSH keys. Github is a web based service to store public and private git repositories. Funtoo is github based.

Setup

Recommended packages

Before we start configuring git we recommend to install keychain on our system to manage the SSH keys. So just type emerge keychain as root.

Backing up existing keys

For security, we will backup or existing keys on ~/.ssh. It can be possible that our .ssh directory it's empty, so this will just throw us a error.

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

Generating a SSH key

Now we will generate a new key for using it with our git account:

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

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

This will ask us where to save the file with a default name id_rsa. If a file exists it will ask us to overwrite so save it as github-ssh-key for example. It will ask us for a password. For that git we recommend to stay with a password-less key just for easy interaction. Anyway, you can add a password for it if you feel more comfortable.

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

Loading the new SSH key

We have to options to load the new ssh key for git: manually or automatically. In any of the two case we will use keychain to load it.

Manually

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

Where our-ssh-key-name is the SSH key we generated.

Automatically

To load the keys manually we need to edit our .bash_profile that will start a background process with the indicated ssh keys. So, edit with our editor of choose ~/.bash_profile:

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

or

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

And add at the bottom of the file as a newline:

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

Where our-ssh-key-name is the SSH key we generated.

Exit with control + 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/our-user/.ssh/our-ssh-key-name
* ssh-add: Identities added: /home/our-user/.ssh/our-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 with the SSH key generated.

Then you need to add the SSH public key to Github so they can recognize your SSH key. This has to be done throw 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 our-ssh-key-name.pub that you can see 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**.