Using git

This page borrows substantially from Tia Newhall's page on revision control software.

git is revision control software that is available on the cs machines and on the machines in SC256. git is useful for managing group projects. For this class you will use git to colloborate with your partner, keep backups of your work, access your work when you're not in the lab, and turn in your code to me.

git allows you and your group members to create a repository for your project source, to each check out your own working copies of your project's source, to commit changes to the repository, to checkout previous committed versions of your code from the repository, to automatically merge in changes made by your project partner(s) into your working version, to create labeled versions of your code, which is useful when using a stable, labeled, previous version as a starting point for other code (you can check out this labeled "starting point" version of your repository code even after more changes have been committed to the repository), to create distinct code branches, ....

There are links to more references at the end.

Below is some information about using git for CS course projects with partners. The first step is to set up a master repository for your shared project, then you and your partner can check out working versions in your own private subdirectories, and push/pull changes to/from the master copy.

Setting up a git repository

For the purposes of this example, let's assume that your username is astudent1 and that your partner's username is apartner2. The instructions also assume that you will be creating a repository called lab01 for Lab 01 and that this repository will reside as a subdirectory in your home directory on the CS machines.

Setting up a master repository to share a project

One of you or your partner should do the following. For the purposes of this example, I will assume that you (astudent1) are setting up the repository.

All of these steps need to be run from your CS account, not from the machines in SC256, and should be done by only one of the two people on a team.

  1. Create a temporary new initial repository (you will delete this in step 4, so don't worry too much about what it's called). The commands to implement each step follows the full set of steps.
    1. make an empty directory to store the initial repository
    2. git init: place existing stuff under git revision control. this creates a .git directory with all git stuff
    3. copy starting point files and subdirectories into your git directory
    4. git add: add everything in project directory to git
    5. git commit -m "created": commit everything to your repository
      6. # Step 1
; mkdir ~/temp_lab01  # create a temporary project directory and cd into it
; cd ~/temp_lab01

# Step 2
; git init

# Step 3: You could copy in and/or create all starting point files
# and directories.  For labs, you probably want to just create a
# simple readme file like this:
; echo "Lab 01" > README.TXT

# Step 4
; git add .   # add all files from top-level project directory

# Step 5
; git commit  # commit the addition of these files to the repository
  2. Next, create the central repository that you and your partner(s) will share. This repository will be created by doing a "bare clone" of the initial repository (git clone --bare). This will be the master repository from which you and your partner will save all changes and retrieve new versions. This repository should be a subdirectory in your home directory on the CS machines so that it is backed up regularly.

    3. In this example, I will place my repository for Lab 01 in my ~/ios/share/ directory. Make sure that the path to the subdirectory is readable by everyone (or at least by everyone with whom you want to share.) One way to do this is using chmod, like the following: 

    ; mkdir -p ~/ios/share  # create the repository in your ios/share directory
; chmod 755 ~/ios/      # anyone can cd into my ios directory and list its contents
; chmod 755 ~/ios/share # anyone can cd into my share directory and list its contents

    Run get clone --bare to create the central bare respository: 

    ; cd ~/ios/share
; git clone --bare ~/temp_lab01 lab01
; ls
lab01/
  3. Next, run easyfacl to set acls on the master repository so that all the members of your group can access it. The text in green below indicates text I've typed in response to the easyfacl command. You'll want to add me to the list of easyfacl users so that I can collect your lab work when it's due. 
    ; cd ~/ios/share/lab01
; easyfacl
Enter a space separated list of users: astudent1 apartner2 richardw
Enter a pathname (relative or full): .    <--- note the green dot

These commands will be entered
setfacl -R -d -m user:astudent1:rwX,user:apartner2:rwX,user:richardw:rwX .
setfacl -R -m user:astudent1:rwX,user:apartner2:rwX,user:richardw:rwX .
Should I do this? (Y/n) Y
acls are set up
press Return>

    At this point, you now have a master repository for your project, that only you and your partners can access. All changes, additions, deletions, to this project can be done with git commands that will push and pull changes from the master copy.

  4. You and your partner should check out code from your central master copy into your own private directories (see the commands for doing this under "Using a shared repository"). You should now remove the temporary repository from step (1). You want to make sure that pushes, and pulls come from your shared central repository and the easiest way to do this is to start with a copy of the repository that you clone from the shared central respository. 

    ; rm -rf ~/temp_lab01

Using a shared repository

After creating the master copy of the repository, both you and your partners should checkout a working copy from the master repository. In CS91, there's never a need to check out your code on the CS machines since you can't compile or run your code there. Instead, you'll need to check out a copy on the machines in SC256 (or your own personal mac laptop/desktop). I'll assume you're working below on one of the machines in SC256. 

; mkdir ~/ios
; cd ~/ios
# If you created the repository, you run this command (change astudent1)
; git clone ssh://astudent1@lab.cs.swarthmore.edu/~/ios/share/lab01

# If your partner created the repository, you run this command (change apartner2 
# to your username and astudent1 to your partner's username)
; git clone ssh://apartner2@lab.cs.swarthmore.edu/home/astudent1/ios/share/lab01
; cd lab01
; ls  #show the files in your local copy of the repository

# FYI: you can look at the git config file to see where 
# the master repository is (to where pull and push go)
; cat .git/config

From your working copy, you can then add files, commit your changes, and push and pull changes to the master. When you create a new Xcode project for Lab 01, you'll want the project to reside in this directory. Let's say that your Xcode project is called DiceRoller. The first thing you'll want to do is tell git to ignore all of the compiled object files that Xcode will create: 

; cd ~/ios/lab01
; echo "DiceRoller/build" > .gitignore

After you've done some work in Xcode, you might want to know what's changed in your version of the code since you last checked it out: 

; git status   #check the status of the local repository

Normally for this class, you'll want to add the entire contents of this subdirectory to the git repository. Note that in projects outside of this course, this is not always the best thing to do. 

; git add .  #put the entire contents of this subdirectory under version control

After you've fixed a bug or completed some milestone, you're ready to commit changes to your local repository: 

; git commit -a  #commit changes to the reposity
This will pop up a vi window and ask you to enter a comment about what's changed since the last time you committed changes. If you want, you can avoid the vi window and write the commit message on the command line: 
; git commit -a -m "This is my initial commit of the DiceRoller project."

Any time you create a new file through Xcode, you'll need to be sure to add it to the git repository and then commit it to your local repository, repeating the commands above: 

; git add .
; git commit -a

When you're finally ready to copy your changes to the master repository (in your account or your partner's account), you need to push the changes: 

; git push

If you've got an existing repository and you want to update it with the latest files from the repository: 

; git pull

Some other commands to see the state of your repository

# see differences between the files in your repository and the last commit 
# to your branch (not comparing to shared master repository)
; git diff

# see the diffs between your files and the last version pushed to the shared
# master repository (the one you cloned from)
# 'master' is your master and 'origin/master'is shared master respository 
; git diff master origin/master

# to see all the branches (in general there should be one for the original
# master, and one each for you and your partner's cloned versions)
; git branch -a

Other useful commands:

 git help      # list common git commands  git help --all lists all commands
 git add       # add changes or new files to the next commit 
 git rm        # remove a file at the next commit
 git commit    # commit your changes to your local repository
 git push      # push your committed changes to the master repository
 git pull      # pull changes pushed to master into your local copy (git will try to merge changes into your copy)
 git mv
 git diff      # see a diff between your copy of a file(s) and the master repository's version
 git status    # see what has changed between your copy and the master version

See the git user's manual and/or git man pages (man git-clone, e.g.) for more commands.

References