RIT/Git introduction

From Teaching Open Source

< RIT

Derived from http://wiki.sugarlabs.org/go/Activity_Team/Git_Tutorial

This is a tutorial which will be used in class Sep. 15th and/or 17th 2009.
RIT and Non-RIT members are encouraged to contribute.

[edit] Git is...

Git is a free & open source, distributed version control system designed to handle everything from small to very large projects with speed, security, and efficiency.

Every Git project clone is a full-fledged repository with complete history and full revision tracking capabilities, not dependent on network access or a central server. Branching and merging are fast and easy to do.

(See Git explained in an IRC log to some new students.)

One typically uses the Git application to initialize a local directory on your computer as your local repository for a project, that is, all the files you want to manage as a project set. (Git rule: one project per directory tree.)

Then, one adds a remote repository URI to the project configuration file.

If you are picking up an existing project from a remote repository, you will clone it to your local directory (initialized as a Git repository), edit or add to the file set, then go through a routine set of Git commands to stage and push your changes to the remote repository. Only secure connections signed with your registered SSH key will be accepted by the host repository, each uniquely signed and clocked on the server.

One pulls changes on the remote repository to update your local copy with changes from others registered on the project.

With an entirely new project, your initial push establishes the remote repository master copy.

Projects Using Git: Linux Kernel, Gnome, Android, Fedora, VLC

[edit] References

[edit] Create an account

Create an account on http://www.gitorious.org by selecting the register link on the home page.

For the projects you will begin this quarter you will be using http://git.sugarlabs.org but we will be using gitorious as our sandbox today.
- Both of these sites serve as top level repositories. Gitorious allows hosting for projects of any nature, while git.sugarlabs.org hosts projects that are to be used with the Sugar learning platform.

Enter your

Login
Email
Password
Password confirmation

Follow link on email confirmation

[edit] Create SSH key pair

SSH or Secure Shell is a protocol that allows two computers to exchange data over a secure channel. The command ssh-keygen creates a pair of keys, one public, which you share with servers, and one private, which is used to identify you by software using the public key, and which you must secure on any computer from which you want to access the server. Keep this key from everyone, or you violate the security contract that only you have the private key.

From the terminal of your machine use the command,

ssh-keygen

When prompted to "Enter file in which to save the key" use the default (/home/olpc/.ssh/id.rsa). Just press 'enter' to accept the default.
Enter a secure passphrase. The software will accept an empty passphrase, but not having one violates your promise that the private key represents you. So keep your private key secure, as a misplaced key allows anyone to impersonate you, eroding the ethic of trust.
To change your passphrase on your current default private key file, use the command,
```
ssh-keygen -p
```

[edit] Upload SSH public key to Gitorious

Copy the contents of /home/olpc/.ssh/id_rsa.pub to the clipboard.
```
cat /home/olpc/.ssh/id_rsa.pub
```
- highlight the key text,
- from the 'Edit' tab, click the 'Copy' icon.
With Browse, go to your account page on http://gitorious.org. (You may need to adjust the page scale by using the Zoom out icon on the 'View' tab (or ctrl + or ctrl - from the keyboard. You also may need to click 'Register now' then the 'Login' link in the upper right corner to get to this https://secure.gitorious.org/login link to bypass the main page login widget, which Browse doesn't like too well.)
Click manage SSH keys.
Click Add SSH Key.
Paste your SSH public key into the text box and click 'Save'.

[edit] Install Git

With the XO (build 803) go to a Terminal session.

su -
yum install git

You will have to accept the recommended files and server certificates.

[edit] Tell Git who you are

In a terminal or console session enter the following:

git config --global user.name "Your full name"
git config --global user.email "Email address"

Make sure the E-mail address you use here (locally) is the same as the ones you used on the remote repository.

[edit] Join an Existing Project

Most people begin working in the open source community by cloning.

[edit] Obtain git commit access

This is required to assure a verifiably secure repository.

Team membership at http://gitorious.org allows many committers to be associated with one or more projects.
At http://git.sugarlabs.org, each committer must be added separately to each project.

[edit] Prepare a local folder

mkdir My_rit_olpc
cd My_rit_olpc

[edit] Clone the Repository

Navigate to http://gitorious.org/rit_olpc/rit_olpc
Note the clone instructions

Clone this repository (Git / HTTP) : git clone git://gitorious.org/rit_olpc/rit_olpc.git

This is displayed in the read-only syntax.

From a terminal, issue instead this command to initialize the working directory, copy and register the files and metadata from the remote repository, and to enable write access to the remote repository:

git clone git@gitorious.org:rit_olpc/rit_olpc.git

This creates a folder entitled rit_olpc in your present working directory inside of which are the project files.
(Git commands written without full file paths must be executed in the local git repository working directory folder?)
If you started out with a read-only clone, change the push url from read-only address by editing the .git/config file of your project folder to: git@gitorious.org:rit_olpc/rit_olpc.git
If you run into trouble and want to start over, just execute these commands:

cd ..
rm -rf My_rit_olpc/

Then begin again at #Prepare a local folder.

You should now be able to go through the normal git add / commit / push sequence after modifying project files in your working copy.

[edit] Create a Project

On http://gitorious.org create a new project by selecting the new link on the project page.

Enter your:

Project Title ("Billy's Personal Projects")
Project slug (This is filled in for you based on your project title)
License (Use the default)
Description ("This is a portfolio of code I have written during my academic career")

There several other question which can be answered later as you have more information.

[edit] Create Local Repository

You may want to create a git_test directory in your home directory (/home/olpc) for organizational purposes.

mkdir git_test

Change directories to your sandbox:

cd /home/olpc/git_test

Finally create and initialize an empty Git repository in the present working directory:

git init

Note

The location of the local repository metadata is in a hidden directory within the git_test directory.
/home/olpc/git_test/.git

[edit] Set the Git push address

On the repository page of gitorious.org you will be provided with the following two pieces of information:

Clone this repository git clone http://git.gitorious.org/example_project/project_name.git
Push url: git@gitorious.org:example_project/project_name.git

These are addresses your local instance of Git will use to communicate with the remote (top-level or master) repository.

In your git_test directory give the following command:

git remote add origin push_url

In this example

git remote add origin git@gitorious.org:example_project/project_name.git

[edit] Push project to the top level repository

We need to create a file or files in our project directory so git has something to monitor the progression of.

[edit] Create a file

In the project directory (/home/olpc/git_test) run vi.
vi is a text editor available from the command line.

vi file

Begin insert mode by typing "i" - You may now edit the file.
Add some lines: ("code would go here") etc.
Save the file. Press Esc, followed by the colon (:), followed by wq (standing for write and quit) Enter.
Verify that you created and successfully saved the file named file.
```
 cat file 
```
You should see the text you just saved in file.

[edit] git add

We are now preparing to push the updated project, which now contains a file, to the remote repository.
In order to do this we need to tell git which files have been modified.

For specific file(s) one enters their paths (here we assume you are in the working directory folder).

git add file file1 file2

For all file(s) in the folder:

git add *

[edit] git commit

After telling Git which files have been updated, we need to record those changes into the local repository.
Each time you make a commit, you enter a comment (a reason for change statement) about the changes you made, so other developers working on the project can take a quick inventory of recent changes, or so one can later understand what was happening at that stage of development.
Issue the following:

git commit

This will open the vi editor you used earlier. Enter an appropriate commit message like "initial commit of test file"
Save your commit comments.

[edit] git push

Now we have to sync the remote, master repository with our local repository.
For an entirely new remote repository, this is done using:

git push origin master

I got this message: --FGrose 22:26, 14 September 2009 (UTC)

To git@gitorious.org:rit_olpc/rit_olpc.git
 ! [rejected]        master -> master (non-fast forward)
error: failed to push some refs to 'git@gitorious.org:rit_olpc/rit_olpc.git'

This is a misleading error message that seems to mean (in some cases) that you need to do a git pull to refresh your local repository for changes in the remote one. --FGrose 06:07, 15 September 2009 (UTC)

I understand now that I had executed this command on an existing repository.

After the inital push one can just use:

git push

(Make sure you are in the root working folder.)

[edit] Tips

Combine, git add *, git commit into one command:

git commit -a -m "I am the commit message"

[edit] Obstacles

Using Git at the command line requires precise execution of instructions that are very sensitive to the order of execution. One tends to follow the examples like a recipe without understanding the model of the application. There is no continuous graphical display of the state of the local, working copy of the repository to monitor. Perhaps we should intersperse the above instructions with some state displaying examples to help everyone learn the application data and process models.

[edit] Assignment problems

Push an edit to the git@gitorious.org:rit_olpc/rit_olpc/MyNameIs file that includes your name in the list.