For a more complete version of this document see Professor Newhall's page.

git is version control software. It is useful for managing code projects, particularly projects with partners. Using git, you will create a remote master repository (repo) for your project. You and your partners then each checkout (clone) a private local copy of the remote master repo, where you can add and commit changes to your cloned copy. To share local changes with your partners, you push them to the master to share with your partners. Any changes committed to a git repo can be recovered if lost.

This guide provides some basics for using git for CS lab work using Andy's 2014 setup31 and setup40 scripts for collaborative projects. It also has links to additional git resources.

Contents:

• Using setup40:
• using a shared repo: add, commit, push, pull, diff, .gitignore
• Using git status: Does your instructor have your code?
• Merge conflicts: why they happen and how to fix them
• List of common commands and git tools
• Troubleshooting some common problems
• Links to git Documentation and Resources
• Some advanced git features: branches

The first step to using git is to set up a remote bare master repository for your shared project. Next, you and your partner clone local working copies into your own private subdirectories. Finally, you each commit changes to your local copies and push and pull changes to and from the remote master to share work. This is mostly automated through the use of the setup31 and setup40 scripts. If you are enrolled in one of these classes, you can run the scripts and see which assignments and directories you can create.

[~]$ setup40

Usage: setup40 <assignment> <partner>

You need to specify the lab to setup
Here are available assignments to setup
examples  (Individual) 
projects/01  (Partner optional) 

For an individual assignment, you can run

[~]$ setup40 examples
...
Set up repo for examples
type
cd /home/adas/cs40/examples
to create/edit files

For a partner assignment, suppose Molly and Tejas are collaborating on a project. One partner, say Molly, should run

[~]$ setup40 projects/01 tejas

Once Molly's script has finished, Tejas can run

[~]$ setup40 projects/01 molly

Aside: First time users config settings

The setup scripts should take car of initial configurations for first time git users, but in case it doesn't, you may want to run the following commands. You only need to run these if git complains about your email or push default settings.

git config --global user.email "username@cs.swarthmore.edu"
git config --global user.name  "Your Name"
git confit --global push.default simple

Replace the email and name strings with your email address and name. If you have not run these commands, then the very first git commit will fail and tell you to run them.

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

You and your partner will work in your local private copies of the repo. You can add and commit changes to your private copy as you go, and choose when to push your change to the remote master repo. Once you push changes, your instructor or partner can then pull from the remote master into their copy.

An example of a sequence of common git commands:

 # check the status of your repo
 $ git status

 # see the changes to the file (compared to your last local commit):
 $ git diff blah.c

 # add a new file to the repo on the next commit:
 $ cp ~/private/foo.c .
 $ git add foo.c
 # or add new changes to an existing repo file to the next commit:  
 $ vi blah.c      # edit with your favorite editor
 $ git add blah.c  

 # commit your changes (adds and deletes) to your local repository:
 $ git commit

 # push committed changes from your local to the remote master repository
 #  note: the first time you push, you may need to do:
 #        git push origin master
 $ git push

 # your partner can now pull your changes from the remote into their local:
 $ git pull

Some notes about these commands:

• git push pushes changes from your local repo into the remote master bare repo. You can only push changes that included the latest pulled version from the remote master (always do a git pull before a git push to make sure). A push pushes only files that have been added and committed to your local repo.
• git pull pulls changes from the remote master repo into your local. git will try to automatically merge changes into your files. If there are conflicts you will need to fix them and run git pull again.
• git add adds files to your next local commit

    git add foo.c blah.c  # add two specified files 
    git add               # add all files except those in .gitignore file
    git add *.c           # add all files with .c suffix
  

.gitignore

It is useful to add a .gitignore file to your repo. It tells git automatically ignore adding certain files or file types to the repo, such as .o and executable files and editor backup files (like vim .swp files). This way if you do a git add git doesn't try to add all kinds of kooky files to the repo. Here is an example .gitignore file for a C program that build an executable file named myprog:

*.o
myprog
*.swp

You add a .gitignore file to a git repo just like you add any other file:

git add .gitignore
git commit
git push

Common 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 remote master repository
            # (note: the first time you may have to do: push origin master
git pull    # pull changes pushed to remote master into your local copy 
            # (git will try to merge changes into your copy)
git mv      # move a repo file
git diff    # see a diff between a file(s) and latest commit (local repo)
git diff master origin/master  # diff between your copy and master's
git status  # see what has changed between your copy and the master version
git branch -a # see all the branches (likely only master)

git tools:

• gitg and gitk are two gui tools to visualize commit history and branches.

• git commit: sometimes the very first git commit fails and tells you to run git config commands that will create entries in the .gitconfig file in your home directory. Just run these commands (filling in your info, of course), and try git commit again and it should work:

   git config --global user.email "you@example.com"
   git config --global user.name  "Your Name" 
  

• git push: sometimes the very first git push fails with an error. If it does, try this:

    git push -u origin master
  

  subsequent calls to git push should work (i.e. you should not need to include origin master after this first time).

• git pull my partner pushed something new to the repository, that I cannot pull. This usually indicates that acls are not set correctly on your main repository. Contact your instructor for help.

• git pull with merge errors: this problem occurs when changes to the remote repo that you are pulling from conflict in a way that git cannot resolve. You can try running git mergetool. It will help step you through the conflicts and fix them. You can also fix conflicts by hand in your favorite editor. In files with merge conflicts, git copies in the remote version, the common ancestor, and the local version of the modified code that it cannot merge automatically. These three versions are in the file with following syntax:

  <<<<<<
  my local version changes
  ||||||
  common ancestor version 
  ======
  remote version changes that I'm trying to pull into mine
  >>>>>>
  

  In your editor, search for these symbols and fix the code by hand. Then add and commit your fixed version and run git pull again.

• git help: git's help interface to view git manual pages related to specific git commands and functionality.

git documentation sections 1 and 2 in particular are very useful
git user's manual
Andy's git wiki page more complete coverage of common and advanced git feature
git cheatsheet
git magic a good source of information about more advanced and obscure git functionality
converting cvs repository to git

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

git branches are a powerful feature of git but will not be used in CS31 and CS40 in Fall 2014.

Last updated: Monday, September 01, 2014 at 08:57:50 AM