Git How To

Since MegaGlest switched to Git and GitHub in late 2013, we need to use some different commands to work with the (now multiple) repositories.

The engine source code is in megaglest-source, the game data is in megaglest-data. More repositories may be added in the future.

Linux

Getting the code (first time)

Obviously you need to install Git. On Debian GNU/Linux, Ubuntu and derivatives use:

sudo apt-get install git

Without write access

As a "normal user" who does not have write access to the repositories, you do:

git clone --recursive https://github.com/MegaGlest/megaglest-source.git
cd megaglest-source/data/glest_game
git checkout master
cd ../..

** If you've made a quite popular mistake - "cloned repository without data (submodules)", then you should do this:

    git submodule update --init --recursive
    cd data/glest_game
    git checkout master
    cd ../..

That's it. Read on below on how to track updates.

With write access

You are a MegaGlest developer who has already registered with GitHub and has been granted direct write access to the MegaGlest repositories. If so, you should be part of a MegaGlest team which has write permissions to the relevant repositories.

Option 1: Using HTTPS

To use GitHub over HTTPS, you do:

# This will ask for your standard GitHub username and password
git clone --recursive https://github.com/MegaGlest/megaglest-source.git
cd megaglest-source/data/glest_game
git checkout master
cd ../..

That's done. Now read on below how to configure your commit identity.

Option 2: Using SSH

Alternatively, if you prefer to use GitHub over SSH:

First setup SSH access to GitHub. Start by generating a new OpenSSH key pair.

ssh-keygen -t rsa -b 4096 -C "`hostname` -> GitHub (MegaGlest)" -f ~/.ssh/github.com_megaglest_id_rsa

Your new public SSH key needs to be copied to the SSH keys page on your GitHub account:

cat ~/.ssh/github.com_megaglest_id_rsa.pub

Now configure an OpenSSH host profile to make OpenSSH use your new SSH key whenever you try to authenticate to GitHub to work on MegaGlest (you will continue to use your GitHub credentials to login on the GitHub website):

touch ~/.ssh/config
echo '' >> ~/.ssh/config
echo "# Added on `date` as per https://github.com/MegaGlest/megaglest-source/wiki/_pages" >> ~/.ssh/config
echo 'Host github-megaglest' >> ~/.ssh/config
echo 'HostName github.com' >> ~/.ssh/config
echo 'User git' >> ~/.ssh/config
echo 'IdentityFile ~/.ssh/github.com_megaglest_id_rsa' >> ~/.ssh/config
echo 'PasswordAuthentication no' >> ~/.ssh/config
echo 'PubkeyAuthentication yes' >> ~/.ssh/config
echo 'PreferredAuthentications publickey' >> ~/.ssh/config

Now clone the repository. In the first step, OpenSSH will ask you to verify GitHub's SSH fingerprints.

git clone --recursive github-megaglest:MegaGlest/megaglest-source.git
cd megaglest-source/data/glest_game
git checkout master
cd ../..

Reconfigure your local repository to use SSH instead of HTTPS (the default):

git config remote.origin.url "github-megaglest:MegaGlest/megaglest-source.git"
git config submodule.data/glest_game.url "github-megaglest:MegaGlest/megaglest-data.git"
cd data/glest_game
git config remote.origin.url "github-megaglest:MegaGlest/megaglest-data.git"
cd ../..

Configure your commit identity

Whenever you commit, a friendly name and an e-mail address are transferred as part of the Git protocol. So you should now configure your Git username and e-mail address. The e-mail address must match one of the e-mail addresses you have set on your GitHub account's e-mail settings. To not get spammed, activate the keep my email address private option there and use the e-mail address provided below:

git config user.name "My Name goes here"
git config user.email "my.user@some.doma.in"

Repeat for the data repository:

cd data/glest_game
git config user.name "My Name goes here"
git config user.email "my.user@some.doma.in"

Updating from GitHub (regularly)

To synch your local repositories with those on GitHub, change into the directory you initially cloned megaglest-source into. It is probably called megaglest-source.

To update the megaglest-source repository:

git pull

To update the megaglest-data submodule and any other submodules (if any):

git submodule foreach git pull

Useful Git commands

Inspect the state of your local repositories:

git status
git submodule status

Add every removed/moved/renamed file

git add -u

Like above, but also add every new file/directory recursively - beware!

git add .

Fixing mistakes: If you just accidentally added everything (using git add ...), undo all uncommitted changes (bearing a potential for data loss) using:

git reset

Check what was ignored, (probably some junk or nothing):

git clean -ndX

Commit code you just added to your local repository:

git commit

This will spawn an editor (set your preferred EDITOR in ~/.profile) to review the changed files and to add a commit message. Alternatively, pass your commit message directly on the command line:

git -m "My commit message"

Push your changes to the master repository on GitHub:

git push origin master

To do the same for the megaglest-data submodule, change into the data/glest_game/ directory first.

Graphical Git utilities

History viewers:

• gitg - very simple
• gitk - not as simple as gitg, but faster
• qgit - good, but based on qt (i.e. a good match for KDE)

Commit helpers:

• git gui
• git cola