How To Use the Git Repo

What/why?

Git is a version control system: a way for storing a repository of a bunch of files, while keeping track of all previous versions. In the group this is used for storing code and manuscript files. It works best with text files, e.g. \TeX~files or code. Other non-text documents can be stored but it will not be able to `merge' changes made by different users.

Certain things should NOT be added to repositories, as they will cause headaches:

  • Compiled versions of documents (e.g., the PDF produced by a \LaTeX~file or compiled code)
  • Data from experiments (especially if it is large)
  • Any temporary files
  • Anything large (more than a few MB) -- be aware that if a large file is ever added to a repository, a version of it will be stored on ever copy of this repository
Note that you can have files in the directory of a repository without having them in the repository.

Installation

It is possible to use Git from the command line, but a far easier option is to use a GUI. SmartGit is one good option, and is free for non-commercial use. You can find it at http://www.syntevo.com/smartgit/, or find Mac DMG on ImmenseIrvine at labshared3/how_to_use_git_repo/. When you first run it, it will send you through a setup:
  1. On the second page of the setup, check `Non-commercial use only'.
  2. If required, it will ask you to install Xcode/Apple Developer tools.
  3. If you want to open a test repository when it gives the option, see below.

Example Walkthrough

We have a repository named git_test for getting used to Git. Here we clone, edit it, and commit our changes.
  1. At the end of the install script, when it gives you the option, click `Clone and existing repository.' Alternatively, you can go to the menu `Repostitory/Clone'.
  2. Enter the following in `Remote Git or SVN repository': 
            ssh://[USER_NAME]@immenseirvine.uchicago.edu/git/git_test
    where [USER_NAME] is your login for immenseirvine (if you don't have one, ask to get one!)
  3. Click continue, then for SSH credentials click `Password', and enter the password for your immense account. Click `save password' before continuing. It may ask you to set up a master password for SmartGit; if so do it.
  4. Click through the rest. You should now have a folder named git_test in your home directory.
  5. Open a file browser window, and go to the git_test directory, which should now have several text files int it.
  6. Add a line of the text to one of the files and save it.
  7. When you go back to SmartGit, this file should appear on the file list (it was hidden before because it was unchanged).
  8. Click on the file, and you should see your changes.
  9. Go the menu item `Repository/Settings'.
  10. Go to the `Commit' tab and make sure your name and email are correct. Click on `Remember as default' and then `Ok'.
  11. To commit your changes, click the `Commit' button and enter a `Commit Message'.
  12. Click `Commit and Push', this will both commit your changes locally and then copy them to the global stored version on immenseirvine.
  13. If you want to look at a log of changes, click on “Log” on the top bar of the SmartGit window.

Basic concepts

The main actions used are:
  • clone: make a local copy of a repository
  • commit: locally commit your files (i.e. store a version of them in the repository on your local computer)
  • push: push your locally committed changes to the global repository (typically on immenseirvine)
  • pull: pull the global changes from the global epository, merging the changes with your changes when possible
Note: the commit/push cycle is different than SVN. Commits only happen locally; meaning it stores the changes on your computer. Conveniently, this lets you store a version even without internet access. These changes are only added to the global version when you push. Typical usage involves the following steps:
  1. Clone the repository, creating a local directory with the files in it.
  2. Edit these files, or add new ones.
  3. Commit/push your changes. In SmartGit, you must tell it which files to commit (it is possible to update only some files). Please always include a brief description of your edit!
  4. When you are ready to edit again, pull changes and then return to 2.
The easiest way to avoid `conflicts' is to always pull before editing. Changes to different parts of text files will automatically merged; edits to the same part (usually the same line) will need to be `resolved' by hand. This can been done from within the SmartGit GUI, and involves choosing which version of each change to keep.

Creating a new repo

To create a new repo, you will first need the root password for immenseirvine. Once you have this, you can create a repo easily from the terminal: 
    >> ssh root@immenseirvine.uchicago.edu
    root@immenseirvine.uchicago.edu's password: [ENTER PASSWORD]

    >> sh make_repo.sh [REPO_NAME]
    Initialized empty shared Git repository in /volume3/git/[REPO_NAME].git/
    Created new git repo: ssh://immenseirvine.uchicago.edu/git/[REPO_NAME]
We now have a repository that you should be able to clone and start editing!