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.

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

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.

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.

Checking if all worked

Now you can check if all worked. Just run:

~ $ ssh git@github.com -i ~/.ssh/github-ssh-key
The authenticity of host 'github.com (207.97.227.239)' can't be established.
RSA key fingerprint is 16:27:ac:a5:76:28:2d:36:63:1b:56:4d:eb:df:a6:48.
Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added 'github.com,207.97.227.239' (RSA) to the list of known hosts.
PTY allocation request failed on channel 0
Hi <YOUR GITHUB USERNAME>! You've successfully authenticated, but GitHub does not provide shell access.
Connection to github.com closed.

Needed commands for git

clone, pull, commit, push

Git config example

As a nice feature we want to help you set up git so you have a nicer view, for that we edit and/or create two files.

First edit/create the the file ~/.gitconfig

[user]
    name = <Your Name>
    email = <Your email for github>
[github]
    user = <Your github username>
[color]
    diff = auto
    status = auto
    branch = auto
    grep = auto
    interactive = auto
    showbranch = auto
[core]
    editor = <Your prefered editor>
[commit]
    template = ~/.gitmessage.txt

Then create the following file ~/.gitmessage.txt

subject line

config description

[ticket: X]

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. :)