Middlebury

Git

This page provides details on how LIS staff can use Git to collaborate and version-control their projects. Excellent documentation on using Git is available on the web, so this page focuses on our particular work-flows rather than basic usage.

For those looking for more resources for learning Git, see:

Recommended tools for working with Git

OS X

  • Git - The core Git command-line program and the Git-GUI user interface and the Gitk graphical history browser.
  • Source Tree - A nice GUI for working with Git.

Windows

  • Git - The core Git command-line program and the Git-GUI user interface and the Gitk graphical history browser.
  • Source Tree - A nice GUI for working with Git that includes helpers for managing SSH keys.

Linux

  • Git - The core Git command-line program and the Git-GUI user interface and the Gitk graphical history browser.

Remote Linux hosts via X11

One common work-flow is to do your work on a remote Linux host from a Mac or Windows workstation. You will usually open a remote shell via Terminal (OS X) or Putty (Windows) so that you can get a command-line on the remote Linux host. If the Linux host has Git installed, you can use it's command-line interface through your terminal. Additionally, you can usually also use the graphical Git GUI and Gitk interfaces by running an X11 server on your workstation.

The X11 has been around for decades and lets you easily run GUI programs across the network. X11 has an inverted client-server model from what most of us are used to: Your work-station runs an X11 'server' program that draws the GUI on your screen, while the X11 'client' is a program on the remote host that sends drawing commands to the server on your work-station.

  1. Install the X11-server on your workstation.
  2. Open a remote shell with SSH providing x-forwarding.
    • On OS X run
      ssh -X user@host
      Your Terminal should automatically start XQuartz when you run ssh with the -X parameter.
    • On Windows open Putty and _________.

Central Repositories

The .git/ directory in your project is a full 'repository' and contains all of the changes sets that make up your project's history. It is perfectly fine to use git without ever interacting with remote services. That said, often we need to share our projects with others to collaborate as well as to make sure that our valuable efforts are backed up. To enable sharing, we push our change-sets from our local working repository to a central repository that is accessible by others in our 'team'. For our open-source development efforts that we share freely with the world, we use GitHub as our central-repository host as it aids collaboration with others outside of the institution. For projects that we don't share with the world we run a local Gitolite server ([1]) that provides protected project hosting.

git.middlebury.edu

git.middlebury.edu hosts our private git repositories for LIS. Access to these repositories is provided via ssh (for cloning/pushing) and http (for code/change-set browsing). Adam Franco manages access to these repositories.

Web browsing

To browse code and change-sets via the web, point your browser at https://git.middlebury.edu/git/ and log in with your Active Directory credentials. You will only see a listing of projects that you have been granted access to -- contact Adam for additional access if required.

Setting up SSH authentication

Clone and push access to repositories is provided via ssh using password-less (public-key/private-key) authentication. Once your SSH key is configured on your work-station and granted access on the host, your command-line or GUI tools can work with all of your authorized repositories without additional configuration.

  1. Create an RSA public-key/private-key pair.
  2. Send Adam your public key via email. He will add it to the server configuration to provide you access. If this is your first key, please mention which repositories you need access to.
  3. Configure your Git tools to use your new SSH key.
    • UNIX systems (OS X, Linux, etc): Tools using ssh will usually look for a key file in your home directory at ~/.ssh/id_rsa and use that by default. If you only have this one key, you shouldn't have to configure anything else. If you have multiple keys, then you can add an entry to your ~/.ssh/config to force usage of a particular key-file when communicating with git.middlebury.edu.
    • SourceTree on Windows: How do I set up SSH keys for authentication?

Troubleshooting SSH issues

  • The first time you make an SSH connection to git.middlebury.edu you need to add the server's SSH public-key to your SSH client's known-hosts list. The fingerprint should be d8:b5:1b:2f:f5:89:82:ee:0a:ad:4e:8b:f4:3e:a2:b0. Note that some GUI clients are not able to prompt you to accept the public key and will fail or hang if they are the first clients you are using to contact the host. In this case, try cloning or fetching from git.middlebury.edu from a command-line client first.
  • If SSH public-key/private-key authentication is working correctly you should *not* be prompted for a password. If you are prompted for a password then that is an indication that they key-based authentication isn't working for some reason.

Checking your permissions

In addition to fetching/pushing change-sets with git, you can run a command against git.middlebury.edu will allow you to see information about what repositories you have access to. To work, ssh will need to use the same private key that you use for git.

ssh  git@git.middlebury.edu info

Cloning repositories

To clone an existing repository use a 'remote' URL of the form: git@git.middlebury.edu:namespace/project.git where namespace and project identify your particular repository.

For example, to clone the Web team's WordPress project, you'd run
git clone git@git.middlebury.edu:web/wordpress.git
from the command line or use git@git.middlebury.edu:web/wordpress.git as the remote URL to clone from in your GUI application.

Name-spaces

Repositories hosted on our central server are organized into name-spaces for each team. These name-spaces allow each team to create their own repositories and share the same access-control rules for all of their projects. For example, the full-time web-developers all have read, write, and create-repository permission for every repository under the web/ name-space. Name-spaces are simply a permissions-management tool and new ones can easily be created for cross-functional teams that are collaborating on a number of projects.

As well, every user has their own private name-space that only they have access to write to. This private name-space would be appropriate for version-controlling and backing-up your dotfiles, demo projects, or other things that you don't wish to clutter up your teams' spaces with.

Existing name-spaces:

  • web/
  • banner/
  • csns/
  • idm/
  • user/USERNAME/

Contact Adam to create new name-spaces for additional teams or change permissions.

Creating new repositories

If you wish to create a repository in the global name-space or in a name-space you do not have rights to, please contact Adam to be granted rights to that repository name.

For name-spaces for which you have create-repository rights, simply add the destination URL as a remote to your existing repository and push that repository to the new remote.

Here's an example of creating a new project (via the command line) and creating the new central repository in the web/ name-space:

  1. Create a new directory for the project: mkdir hello_world
  2. Change to the new directory: cd hello_world/<code>
  3. Create a file to the project: <code>echo "Hello World!" > hello.txt
  4. Initialize a new working repository in the directory: git init<code>
  5. Stage your file: <code>git add hello.txt
  6. Commit your first change-set: git commit -m "Added the first hello to the world."
  7. Add the central repository as a remote called 'origin': git remote add origin git@git.middlebury.edu:web/hello_world.git
  8. Push your change-sets to the central repository, creating it in the process: git push origin master

Migrating from an existing central repository to the new host

Let's say you have an existing central repository on your development server (as Web Applications does) and you wish to migrate these repositories to git.middlebury.edu. The overall process is:

  1. Add git.middlebury.edu as a remote
  2. Push the repository to git.middlebury.edu
  3. Remove your old "origin" and replace it with git.middlebury.edu

Here are detailed steps for a repository that is shared by several developers A and B as well as a production machine P. Person A will do the migration:

  1. Person A migrates the repository to git.middlebury.edu:
    1. A goes to their working repository and fetches the latest changes from the source repository, origin:
      git fetch origin
    2. A creates a new remote for git.middlebury.edu named new-origin:
      git remote add new-origin git@git.middlebury.edu:namespace/project.git
    3. A pushes all of the branches and tags that were fetched from origin to new-origin:
      git push --tags new-origin +refs/remotes/origin/*:refs/heads/*
    4. A removes their new-origin remote:
      git remote remove new-origin
    5. A updates their origin url:
      git remote set-url origin git@git.middlebury.edu:namespace/project.git
    6. A fetches from the new remote:
      git fetch origin
  2. A informs the team that the code is now on git.middlebury.edu and that they should update their remotes.
  3. Person B updates their origin remote to point at git.middlebury.edu.
    1. B updates their origin url:
      git remote set-url origin git@git.middlebury.edu:namespace/project.git
    2. B fetches from the new remote:
      git fetch origin
  4. Someone updates the production host's origin remote to point at git.middlebury.edu:
    1. Update the origin remote URL on the production machine, P:
      git remote set-url origin git@git.middlebury.edu:namespace/project.git
    2. Fetch from the new remote on the production machine, P:
      git fetch origin
Powered by MediaWiki