Skip to content

git and GitHub

Jump to bottom
goldy edited this page Aug 12, 2019 · 33 revisions

Getting started with git:

  • For a quick, visual introduction to git, try a 5 Minute Overview of Git on Youtube
  • Need an introduction to version control along with git and GitHub? Try Git and GitHub for Poets, a Youtube series
  • For a glossary of common terms used in git and GitHub documentation, see the GitHub glossary.
  • GitHub's Git Handbook offers a brief overview of git and GitHub, including example workflows and links to more in-depth resources.
  • Software Carpentry offers a hands-on introduction to git.
  • A highly-regarded, comprehensive git reference is the book Pro Git (available as a book or a free pdf).
    • The first three chapters of Pro Git, along with sections 6.1 and 6.2 on GitHub, are particularly useful if you're getting started with git. [1]
    • The site also contains links to git reference pages along with introductory videos on git.
    • You can skip the last section of chapter 3, on rebasing, until you have more experience with git. It's easy to cause problems for yourself or others with rebasing so only use rebasing in CAM following the workflow instructions below as rebasing rewrites history, which can make it impossible to reproduce exactly what you have done before.

Git also offers extensive built-in (i.e., command line) help, although it can be hard to understand until you are familiar with basic git concepts:

% git help

% git help COMMAND

man gittutorial

man giteveryday

How to set-up your git development environment

There are several stages in setting up your git and GitHub development environment. Below, they are broken into three sections which represent the different stages:

One time GitHub setup

  1. Set-up personal github account (if one does not already exist):

    https://github.com/

  2. Create a new personal CAM Fork of the NCAR/CAM repo:

  3. Set up SSH keys on GitHub (optional):

    If you will be pushing changes to GitHub (either to your own fork or to shared forks), or if you will be pulling changes from private repositories on GitHub, then it's worth the time to set up ssh keys for each machine you'll be using. By doing so, you won't have to enter your password when pushing to or pulling from GitHub.

    See https://help.github.com/articles/connecting-to-github-with-ssh for instructions. After doing this, you can use the ssh form of GitHub URLs (e.g., [email protected]:ESCOMP/cam.git) in place of the https form.

  4. Configure GitHub notifications (optional): It is important to keep track of activity on GitHub but there are ways to manage how you are notified.

    • Controlling how you receive notifications: Click on your profile picture in the upper-right of any GitHub page, then click on "Settings", and then on "Notifications". You will see several options, here are a few recommended settings:
      • Automatically watch repositories: Yes (check box)
      • Participating: Email
      • Watching: Web
    • To see and manage Web notifications: Click on the bell in the upper right of any GitHub page to see Web notifications and to manage which repositories you are watching. There will be a blue dot on the bell if there are new (unread) notifications).

Set up git environment on new machine

git has global settings which apply to all repository clones on your machine. These settings reside in a file called .gitconfig in your home directory. Below are some required and some optional but recommended global git settings to apply to any new machine where you will do CAM development (e.g., Cheyenne, Izumi, personal laptop). Apply the settings below or simply copy a .gitconfig file from a machine that is already configured.

Required git global configuration settings:

% git config --global user.name "Your Name"
% git config --global user.email <GitHub email address>

We recommend that you use your UCAR email address as your GitHub email address but if you use another address, you can add your UCAR email address by clicking on your profile picture in the upper-right of any GitHub page, then clicking on "Settings", and then on "Emails".

Recommended git global configuration settings:

You can set which editor to use for log messages, etc., with:

% git config --global core.editor <editor of your choice: emacs, vi, vim, etc>

(See http://swcarpentry.github.io/git-novice/02-setup for specific settings to use for many common editor choices.)

The following setting generates better patches than the default:

% git config --global diff.algorithm histogram

The following setting makes it easier to resolve conflicts if you're doing conflict resolution by hand as opposed to with a dedicated conflict resolution tool. Without this setting, you'll just see your version and the version you're merging in delimited by conflict markers. With this setting, you'll also see the common ancestor of the two sides of the merge, which can make it much easier to figure out how to resolve the conflict:

% git config --global merge.conflictstyle diff3

Alternatively, look into using a graphical conflict-resolution tool such as kdiff3 or the Emacs built-in M-x vc-resolve-coflicts.

git tools for Bash

There are two helpful things you can do to streamline your use of git if you use the bash shell. These are completely optional, but improve your git experience. These are documented in the appendix of the excellent Pro Git book.

Working with clones

Here are some commands for creating and working with clones:

Create a new clone:

% git clone https://github.com/<GitHub userid>/CAMdev
% cd CAMdev

or

% git clone [email protected]:<GitHub userid>/CAMdev
% cd CAMdev

where <GitHub userid> is your GitHub account login ID. Some useful options to the clone command are:

  • --origin <origin name>: A clone knows where it came from and by default, calls that location, "origin". You can change that name with the --origin option. This can come in handy when dealing with multiple upstream repositories.
  • Change the clone directory name: By default, the clone is created in a directory with the same name as the repository. You can change this by adding a directory name to the clone command. Use the appropriate example below:
% git clone https://github.com/<GitHub userid>/CAMdev  <clone_dir_name>
% cd <clone_dir_name>

or

% git clone [email protected]:<GitHub userid>/CAM <clone_dir_name>
% cd <clone_dir_name>

Adding remotes (new upstream repository locations)

While working with clones created using the methods above will be sufficient for most if not all of your development needs, there may be times when you will want to access or compare your code with code from a different repository. git has no problem storing revisions from multiple repositories in a single clone!

To begin, your clone probably has a single remote (also known as an upstream repository). To see the current status of which upstream repositories are configured for your clone, use the git remote command:

% git remote
origin

To see the location of the remote repository (origin in this case):

% git config remote.origin.url
https://github.com/gituser/CAMdev

To add a new upstream repository, use the remote add command. For example:

%  git remote add ESMCI https://github.com/ESMCI/CAM
%  git fetch --tags ESMCI

You should see messages much like a new clone when you execute the git fetch command.

CAM wiki

CAM Documentation

CAM Model Development

Clone this wiki locally