Getting started with git

CS 300, Parallel and Distributed Computing (PDC)

Git is a version control system that enables a whole team to share development of a project, even if they are located at great distances from each other. It retains prior versions, so files can be "rolled back" when necessary, and it prevents one person's changes from overriding other changes when used correctly. Git is also widely used for sharing software with others.

We will use this versatile tool as an optional alternative to ppsubmit for submitting your work. These steps provide you with an introduction to git.

1. We created an account on St. Olaf's git server "stogit". We also created a private git project repository for you, and added your account to have access to it. It's easy to create new projects, but we need to locate your project within a group for the course to insure that it will be private for your work yet accessible by TAs and profs.

2. For the command-line instructions below, our git server authenticates you using passwordless SSH. In order to set this feature up,

   1. On a Link computer at a terminal prompt, create a SSH key pair using the following command. Note: If you already have a public key file ~/.ssh/id_dsa.pub or ~/.ssh/id_rsa.pub, then you can skip this step a. and use that file for step b.

      %  ssh-keygen -t dsa 
      

      By default, this will create a "public key" in the file ~/.ssh/id_dsa.pub .

      If you already have a public key on the link machines, you can use your prior public key instead of generating a new one.

   2. Visit stogit.cs.stolaf.edu in a browser, and open your Profile settings (there may be an icon for this), then select "SSH Keys" from the menu bar. Give a name to your key (such as "Link machines"), then cut and paste the public key (contents of the .pub file above) into the larger text box. Then click the submit button for your key.

   Note: It is also possible to interact with git using the web interface you used to create an account, by logging in and supplying your password. The command-line interface below reveals more about how git works, and can be automated into shell scripts or makefiles.

3. The following commands, which only need to be executed once for your computer account, provide identification for git interactions over ssh.

   %   git config --global user.name "Your Name"
   %   git config --global user.email "user@stolaf.edu"
   

   where user is your St. Olaf username.

4. Now, you're ready to make a clone of your team's git project on your computer's file system.

   %   cd ~/PDC 
   %   git clone git@stogit.cs.stolaf.edu:pdc-i14/proj.git ~/PDC 
   %   cd proj
   

   where proj is your git project's name, the same as your username. (Note: Use your username, not "proj".) This creates a local git repository for working on your project. The clone operation copies any files that are already in the git project to your directory ~/PDC, and prepares that directory for tracking changes you make. You will be able to change files, add new files, and upload the changes to git in order to share your changes.

5. Now, create a new file in your repository with your username, and add it to the project, for purposes of getting familiar with git. (This file can be removed from the project later.)

   %   (edit user.txt using your favorite editor, and insert one line)
   %   git add user.txt
   %   git pull
   %   git commit -m "message"
   %   git push
   

   Here, message is a description of the changes you want to add to the git project. This pattern of adding modified (or new) files, pulling, committing, and pushing, will be the usual way to upload changes you make to your team's git project on stogit.

   Note: The order of these operations is important.

   • The git add instruction identifies which files to upload, including new and modified files. There are other ways to do this step (see note below), but it must happen before or during the git commit step.

   • The git pull command fetches a copy of the git repository from the stogit server. You need to pull before commit in order to detect conflicts between your work and changes others may have made recently.

   • The git commit command attempts to incorporate your work into the "snapshot" of the repository that you just pulled. We describe below how to recover if there is a conflict between your work and someone else's.

     Note: Be sure to use the -m "message" option for git commit in order to indicate the work you are trying to commit to this git project. The purpose of the message is documentation, so you can identify old versions when needed without laboriously retrieving them all and trying to identify from the code what changed in each commit. If you don't use -m, git will pop up an editor for you to enter that message.

   • All of add, pull, and commit must succeed before you can upload your changes to the git project on the stogit server using git push.

   Note: Be sure to specify which files are to be included in the upload to the repository. You can use the git add command as above; an alternative is to use git commit -a to automatically add all files in your local repository. The documentation for git commit lists more options for adding files to be committed.

Congratulations! You have now set up git on your computer, and contributed a new file to your git project!

Note: You can only clone a non-empty git project, i.e., a project that already contains at least one file. We have create an empty README file in your project for you, for this purpose. If a git project does not yet contain a file, you can create a local repository and create a file without cloning as follows:

%   cd ~/SD
%   mkdir proj
%   cd proj
%   git init
%   touch README
%   git add README
%   git commit -m 'first commit'
%   git remote add origin git@stogit.cs.stolaf.edu:pdc-i14/proj.git
%   git push -u origin master

rab@stolaf.edu, January 6, 2015