Git Guide

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 git based and stored at github.

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.

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.

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.

Configuring Github

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.

Select Account Settings

Click on Add another public key

Save the key

If you have now added you first github repository you can start working with it.

If you now do a commit, you don't need to enter the complete base frame everytime on your own. Git will open your editor set in .gitconfig and show you the .gitmessage.txt where you could replace the first 5 lines with a description about what you did and why, but please never edit the lines after [ticket: X] in the upcomming window. :)