Activity Team/Git Tutorial

GitHub
Sugar Labs uses GitHub as its primary server for git repositories. While you are welcome to use other servers, it is on GitHub where you will find the master branches of the core modules and core activities.

Getting started with GitHub

You will learn to do the following:
 * Create an account, which you do once.
 * Create and add an SSH key, which you do once or if you change system.
 * Create a project, a local repository, and identify yourself to git, which you do once per project.
 * Add source files, change existing source files, commit changes, push changes, and pull changes, which you do regularly.

Create an Account
Create an account here

Create SSH Key on Windows
To create an SSH Key on Windows, download the latest PuTTY installer.


 * Run the puttygen.exe utility to generate a pair of private/public keys.
 * Click on the Generate button (Make sure SSH-2 RSA parameter is checked)
 * Move the mouse around to generate your key.
 * Once you have accumulated enough "heat", the application will generate your key pair.
 * Make sure you enter a lengthy passphrase in the Key passphrase field and confirm it in the Confirm passphrase field.
 * Click on the Save private key button to save your private key in a file.

Congratulations! With your mouse, select the content of the box labelled Public key and press Control-C to copy your public SSH key. This key can now be used on GitHub to access Git on Windows. Good luck!

Create SSH Key on GNU/Linux
Skip this section if you already have an SSH key in .ssh directory that you trust.

(An easy-to-read tutorial for generating an ssh key can be found here.)

To create a key use ssh-keygen. The following command will create a “dsa” key: ssh-keygen -t dsa

For creating a “rsa” key use: ssh-keygen -t rsa

The key will be stored as two files in the hidden .ssh directory.

id_dsa.pub is your public key. id_dsa is your private key. Only you should have access to this private key. Access to the key will grant access to GitHub in your name. For example, here is a list of files in the .ssh directory of user strom: ls -al ~/.ssh -rw---  1 strom strom  668 2009-12-17 21:51 id_dsa -rw-r--r--  1 strom strom  603 2009-12-17 21:51 id_dsa.pub

You should only need to create a key once, unless you change to another system, or a different Sugar-on-a-Stick drive, or you think your private key was compromised. If you do it again, you must also add the new key to GitHub as described in the next section.

Setup Git for Windows 8
GitHub is one way you can set up Git on Windows 8. It can be downloaded from here

Once downloaded and installed, Git Shell can be used to execute Git commands.

Add SSH Key
Log in to GitHub at http://github.com and go here click on 'Add Ssh Key'. Choose a title. Open your public key in a text editor, web browser, or even cat command, and then copy and paste the key into the text entry field. Click on Save.

Once you do this, GitHub trusts SSH connection from your system because your system has the private key, and GitHub has the public key. You should only need to do this once, unless you change to another system.

(With ssh-keygen you can specify the name of your key file. Using this feature is not a good idea, because we haven't tested it. Keys should generally be located in ~/.ssh/id_rsa.pub or ~/.ssh/id_dsa.pub.)

Create a Project
Log in to GitHub at http://github.com and go here. Choose a repository name, and write a description.

Create Local Repository
Clone it from GitHub: git clone git@github.com:username/${SLUG}.git ${SLUG}.git

Replace ${SLUG} with your project slug value.

Once you do this, you will have a local repository directory named ${SLUG}.git that shares the same history of changes (if any) of the repository at Sugar Labs. You should only need to do this once for each project and system. You can do it again if you need a fresh copy that has no changes.

Identify Yourself to Git
Git on your local system must know your email and name. It uses this when you commit a change, so that when you push or mail it others will know who did it.

If you do not use git on your system for any other project, you can configure git:

git config -f ~/.gitconfig user.email  git config -f ~/.gitconfig user.name 

You should only need to do this once on a system.

Otherwise, configure git in the repository:

cd ${SLUG}.git git config user.email <email-you-used-for-registering-project> git config user.name <your-name>

You should only need to do this once in a repository.

Develop
Use a text editor or integrated development environment to create new source files or change existing files. Test the results by running the activity. Do this from your local repository, or from elsewhere - then copy your files to the repository. Repeat until you are satisfied with the changes you made.

Commit Changes
In your local repository, find out from git what files you changed: git status

Add any files that are new or changed: git add ...

Tell git to collect the changes into a commit: git commit

You should do this for every meaningful set of changes you make.

Note  commits your changes to your local repository only.

Request Review
Before you publish changes widely, you can ask others to review your work and comment on it.

git format-patch -1

or

git send-email

You may do this for every set of changes you make.

Push Changes
Your changes have to be pushed from your local repository to the repository at git.sugarlabs.org so that others can see them there.

git push

You must do this for every set of changes you make, when you want to synchronise with other developers or prepare for a release.

Pull Changes
Others, including pootle, may add changes to the repository at git.sugarlabs.org. You must merge these with your repository.

Use git pull

Also, run python setup.py fix_manifest to update the .mo files after updating the .po files

You should do git pull frequently; before starting development, before pushing changes, and when you see other developers commit changes.

Tags
alsroot taught me about another git feature: tags

git tag -m "Release 36" v36 HEAD git push --tags

What Pull Does
bertf explained to me that git-pull does a combination of fetch and merge, so to merge a patch...

git pull git://github.com/username/project.git master