Lab: Getting Started with GitHub

Summary

This laboratory helps you get started with Git capabilities, specifically utilizing GitHub at github.com. Some details of the discussion related directly to the use of GitHub for assignments in this course.

Background Reading

Before working on this lab, be sure you have read Professor Rebelsky's reading on Getting Started with GitHub. The first part of this reading provides important background on source code management, as well as an overview of GitHub. Later parts of the reading contain substantial detail in the use of GitHub.

Acknowledgments

Much of this lab comes from edited versions of materials written by Samuel Rebelsky and revised by Jerod Weinman. Thanks also to Carlton Segbefia and Brandon Thomas for their help in experimenting with GitHub Classroom and with reviewing details of this narrative.

Lab Overview

Activities within this lab involve four main elements:

1. Creating a GitHub account (if you do not already have one)
2. Accessing a course assignment for individual or collaborative work
3. Connecting a GitHub Classroom Assignment to MathLAN or your laptop
4. Working with your partner and the GitHub repository for the assignment

Creating a GitHub account

You will need a GitHub account throughout this course, but fear not: Set up of a GitHub account is reasonably easy and free!

If you already have a GitHub account, you do not need another one— just skip this section.

If you do not have a GitHub account, follow these steps:

• Go to https://GitHub.com.
• Pick a username, indicate your email address, and choose a password (with at least one letter, one number and at least seven characters).
  If GitHub determines your username has already been taken, you will be asked to pick another username.
• Click the button "Sign up for GitHub".

Once you have an account established, you need to select some options and you are encouraged to provide some general background information.

• Choose the various free options (e.g., public repositories)
• Indicate how long you want your account retained.
  (Outside of class, you may want to upload parts of a portfolio containing selected pieces of your work, that you might share the material with potential employers. To be safe regarding duration, you might indicate a duration of at least a year, or you may wish to leave the duration open for now.)
• Since you likely will be the only person using your account, the number of people likely should be one: just you.
• During account set up, GitHub may send you email to verify your address. Check your email periodically and respond as directed.

Accessing a course assignment on GitHub for group or individual work

For this course, we will use a component within GitHub, called GitHub Classroom. For this course, a "Classroom" has been established, called CSC-207-02-Fall-2018, and I have entered the names of students for this course. Through the semester, I will create assignments on GitHub Classroom and reference them in labs and supplemental problems.

The process of getting started is somewhat different for work in pairs (e.g., labs) and for individual work (e.g., supplemental problems).

Collaborative Work

For collaborative work (e.g., for labs), partners (usually 2 students) will establish a "team", and each team will establish a "repository" within GitHub for its work. As might be expected for pair programming within a course, the work of each team is considered private; students outside a team will not be able to view work of another team. (However, for grading, both the instructor and the graders will be able to access team material.)

Logistically, getting started with a course assignment will involve using a GitHub URL for that specific assignment. For this lab, use the link https://classroom.github.com/g/Tjz-jPTO.

After utilizing the link, one lab partner will create a team and the other partner will join that team. Specifically,

• Find your name on the roster, and click on it.

• Determine if your lab partner has already created a team for your pair on this assignment.

  • If so, click the join button for that team.
  • If not, determine a team name for this assignment, and click the button to "Create team"

Individual Work

Supplemental problems will be established as individual activities, and each student will have a private repository (again, both the instructor and graders will have access).

Naturally in this context, you will not be creating a team! However, you likely will need to identify yourself and click the button to "Accept this Assignment". You also may receive email to verify your authorization. (If you receive such email, you should respond as directed.)

For either collaborative or individual work

Once you have set up a team, if necessary, and accepted the assignment, you will be directed to a page, "You are ready to go!"

On the "ready to go" page, click the link for "Your assignment has been created here".

If all goes well, you will be directed to a page that identifies several options.

• From a broad perspective, you will need to create a repository in which you (and your partner) will place assignment materials as they are developed.

• GitHub provides several approaches for creating repositories and uploading versions of materials, as they are developed.

• For this course using GitHub Classroom, it is strongly suggested that you focus on the option to create a new repository, using a terminal on your local machine (e.g., MathLAN or your laptop). This is the second option presented on your "assignment has been created page."

• From GitHub's "assignment created" page, copy into a temporary file the terminal commands below the title, "or create a new repository on the command line". Do not run these commands—yet!

Connecting a GitHub Classroom Assignment to MathLAN or your laptop

When you have registered (individually or with your team) for a GitHub Assignment, you will want to connect your MathLAN account or laptop to that assignment. When you are using both MathLAN and your laptop, or when you are collaborating with a partner, this connection process involves two components:

• Setting up an original GitHub repository on a first local machine
• Connecting other machines to the GitHub repository

Setting up an original GitHub repository on a first local machine

This is accomplished by typing commands in a terminal window.

• Create a directory for work with GitHub and this Lab. Prof. Rebelsky recommends ~/CSC207/Git

• Configure your account to work comfortably with GitHub
  Set up your local git environment with these commands in a terminal window:

  • Start in your home directory
  • Identify yourself as connected to files you may upload.
    git config --global user.name YourName
  • Identify the email address used for your GitHub account
    git config --global user.email username@grinnell.edu
  • Select your preferred editor (e.g., emacs, vi, vim, gedit, etc.
    git config --global core.editor editor
  • Enable the use of color in Git command-line output:
    git config --global color.ui auto

• Move to your course/GitHub directory (e.g., ~/CSC207/Git)

• Create a subdirectory for this lab/assignment (e.g., github-exercise), and move to it.

• For any substantial software project, best practice requires that you include a "README" file that explains briefly what the software does and gives information about the current version of the project. At the start of a project, the README description may be quite brief—just identifying the project's title. As the project develops, this description may be expanded periodically.

  The first line identified on GitHub's "Assignment created" page creates a simple README file, likely indicating a variation of the following:

  • Create a README.md file to help viewers of this assignment, when it gets uploaded to GitHub
    echo "# first-assignment-using-github-team2" >> README.md

The following lines are edited and simplified versions of instructions from GitHub help.

• Initialize the local diretory as a Git repository

  git init

• Add the files in your new local repository and stage them for the first commit.

  git add .
  
  Not all files within a directory are considered part of a Git project. Rather you need to add the file names that should be tracked.
  For example, you might add .c files for a C program and .java source code, but you likely would not include compiled files, such as .o files in C and .class files in Java in your Git repository.

• Commit the files that you've staged in your local repository, and prepare them to be pushed to a remote repository.

  git commit -m "First commit"
  

• Go to your GitHub "Assignment page" and the box for a new repository, and copy the URL given for this assignment

• Connect your local repository with the GitHub assignment repository

  git remote add origin remote-repository-URL

• Verify the new remote URL

  git remote -v
  

• Push the changes in your local repository up to the remote repository you specified as the origin

  git push -u origin master

Connecting other machines to the GitHub repository

Once a repository has been established on GitHub Classroom for your team's assignment, your partner can connect to it on any machine and you can connect on a different machine as follows:

• Log into GitHub with your username using the command
  
  git clone https://GitHubUsername@URL from GitHubAssignment
  
  You will be prompted for your GitHub password

  Example: if your username is henry-walker and the URL for your GitHubAssignment is https://github.com/orgs/CSC-207-02-Fall/lab-assignment-intro-github-my-team, then you would type:
  
  git clone https://henry-walker@github.com/orgs/CSC-207-02-Fall/lab-assignment-intro-github-my-team/

Working with your partner and the GitHub repository for the assignment

After you have established a local Git directory and connected that directory to a GitHub assignment, you will want each work session to begin with the current version of the project/assignment. Variations can arise if you work on both MathLAN and your own laptop, or if both you and a lab partner are collaborating.

To resolve possible version-control problems follow these steps for each work session:

• Move to the directory with your project.

• Retrieve the most current version:
  git pull

• Work on your project:

  • Add files to the Git project:
    
    git add filename
    
    
  • When completing a stable version of some step in the project, record the updated project to the local Git repository
    
    git commit -m note about what has changed
    
    
    • Commit frequently, so you can retrieve a past version if you screw up with the current one!
    • Do NOT commit code that does not compile!
  • Near the end of your work session, send the new version of the project to GitHub:
    
    git push

Resolving Conflicts

Suppose you have changed a file (e.g., on MathLAN), but you made a different change on another machine (e.g., your laptop), or your lab partner also made a change. Overall, there are two versions of the project, and the differences need to be resolved.

Git identifies such conflicts when you issue a git pull command; a message, such as the following might appear:

   Auto-merging FILE
   CONFLICT (content): Merge conflict in FILE
   Automatic merge failed; fix conflicts and then commit the result.

<<<<<<< HEAD
        CODE
=======
        OTHER CODE
>>>>>>> 68f7b764bb0e83971245e8db7e58c330c9d9d25c

These lines show the discrepancies between the two versions, and you should edit the file to indicate the correct version.

With this completed, in a terminal window, use the add and commit commands to update Git. Then try another pull—the difficulty should be resolved!

created 13 September 2018 last revised 15 September 2018
For more information, please contact Henry M. Walker at walker@cs.grinnell.edu.