Git Lab: Gitting--er, Getting Started

Due Sunday Monday at 11:59 p.m.

Background

Knowing how to use a source control system will be an invaluable tool for you, especially in a team setting. At its heart, version control is a way to manage the changes that occur to your files over time, but that simple idea changes everything! It allows you to revisit previous versions of your code, work with different versions at the same time, and work in teams and track who made which changes. At its best, version control is like a journal that you use to track major, and minor, events in your project. At its most practical, it is like a backup system that prevents you from losing significant work if something happens to your machine. At its worst, it is simply a submit system where you only track your work when told to.

Version control systems have been around for over forty years, and Git is currently the cool tool to use. You may have heard of GitHub, the largest public repository of source code, but there are lots of places where you can host repositories. We will be using GitHub Classroom to coordinate assignments and projects.

Using source control well is not difficult, but it does take some practice and a little bit of command-line savvy (we will not use visual Git tools until you are confident in your version control skills).

Objectives

• To create a GitHub account
• To learn to use Git from the command line.
• To learn to use GitHub classroom with Canvas

Part 0: Set Up

Install and Set Up Git

• If you only plan to use the lab machines, you can skip this step. On Mac or Linux, Git may already be installed. Follow the instructions here: Download and install Git
  On Windows, there are some settings you should set to work well with other platforms and it comes with a program called Git Shell that you can use to enter the commands below (you can also install a full version of Ubuntu Linux!)
• Within Terminal/Shell, configure Git for your computer (note, these commands only need to be done once for each computer you want to use git on)-- make sure to replace the information as appropriate
  

      git config --global user.name "YOUR NAME"
      git config --global user.email "YOURUSERID@mail.wlu.edu"

• When commiting, git automatically opens an editor to write/save the commit messages. It seems that most systems are defaulting to using vim for the editor, which many of you probably don't know and it has a learning curve. If you want to change the editor that is used for git, see these examples.

Creating Your GitHub Account

If you don't already, you should get a GitHub account.

GitHub Classroom

• Go to the assignment invitation
• Accept the Lab 0 assignment. This will create your own private repository for the assignment.

Part 1: Practicing Git

Git Resources:

Reference these resources to help you use Git

• GitHub Guides: Git Handbook
• An interactive resource: Learn Git Branching may help -- you probably just need Main: Introduction Sequence and Remote: Push & Pull -- Git Remotes

Clone Your Remote (GitHub) Repository

1. In a terminal window, navigate to the directory/folder where you want to store your code repositories for this class. (You may need to create that directory first.)
2. In GitHub classroom, copy the https repository URL from the "Code" button.
3. Run the command:
   git clone <your repository URL>

   If you see an error about needing an access token, create a personal access token.

Learn about Git and GitHub

1. In your browser, go to your GitHub repository for this assignment. The README.md file is rendered and displayed below the top-level source code.
2. Open README.md in your favorite text editor. Compare the contents of the file to what is displayed. How is a top-level heading represented?

   The .md extension means that it is a Markdown file. Markdown is a commonly used markup language to go from text to HTML. It's used to make pretty documents for the Web easily. Markdown is rendered by GitHub's web interface. Markdown has a relatively easy syntax to use. We'll come back to this later.

3. Read the README.md file to learn about Git and GitHub.

In general, a README file gives a user information about software. We'll also use the README file to help us communicate between student and professor.

Create and Add Files in Your Local Repository

• Create a new file called myfile.txt within your cloned repository. You can create this file using whatever text editor you like, e.g., jEdit, Atom, VSCode, emacs, vim, nano, even Idle.
• Within the file, write, "This is my first file for my repository." Save the file.
• In your shell, make sure that you are within your repository, and then add the file to your repository by running
  git add myfile.txt
• Check that you added the file to the staging area by running
  git status

  You should see something like:

  On branch main
  Changes to be committed:
    (use "git reset HEAD ..." to unstage)
  
          new file:   myfile.txt	

Commit Your Updates

Now it's time to commit that new file.

• Run git commit
  This will commit the files you staged.
  You will be prompted to enter a commit message. Say what you did, e.g., "Created a new file to try out git."

  Here is where students are running into trouble -- typically because the default editor is vim and they aren't sure how to use it. In vim, you can save your message by exiting out of insert mode by hitting ESC. Then, use :wq to switch to the command mode, write the file, and quit.
  If you don't want to use vim, go back to the Set Up step and update the editor being used.
  If you're seeing errors like command not found, it's likely that your text editor is not set up to be run through the command line. See the git FAQ for some help.

• Now, if you run, git status, you should see

  On branch main
  nothing to commit, working tree clean
  

Push Your Updates to the Remote (GitHub) Repository

• Run git push to push the local repository to the remote repository.
• You can check the remote repository within GitHub's web interface to confirm that myfile.txt is in the repository.

Update Files in Your Local Repository

Now, let's create an About.md file.

• Using your favorite text editor, create About.md so that it contains a top-level heading (using one "#") that says "About Me". For compatibility, there should be a space between the last "#" and the heading.
• Under that heading, write your name with your class year, e.g., "Sara Sprenkle, 1999". Save the file.
• Add a level 2 heading (still using two "#") that says "Honor Pledge"
• Under that heading, write the honor pledge ("On my honor, I have neither given nor received any unacknowledged aid on this lab.") Then, type your name as a signature. Save the file.
• Adapt the steps from above to add About.md to the staging area, commit the changes with a descriptive message, and push the latest commits to the remote repository.
• Look at About.md in the GitHub web interface. Confirm that it's being rendered appropriately, with the two headings. How cool is that?

Creating and Merging a Branch

Branching helps you by creating a separate sandbox to play/write code and then merge back into your main branch when you're ready.

1. Create a branch by running git branch practice. You are still in the main branch at this point.
2. Switch to the practice branch by running git checkout practice
3. Run git status to confirm that you're on the practice branch.
4. Update the About.md file to add another paragraph under your name where you list your majors, e.g., "Majors: Computer Science and Mathematics". (Note: A paragraph, not a new section.)
5. Update the About.md file (below the majors but above the honor pledge) to add a new section with a heading of "Hobbies" that describes your hobbies outside of coding and another section with the heading "Fun Fact" that gives a fun fact about yourself.
6. Update the myfile.txt file to add another line that says "Please look at the README file."
7. Add both files to the staging area (you can do this using either one or two git commands) and commit them both at the same time, with a descriptive message.
8. Push this branch to remote by running git push origin practice. This command is longer than before because the practice branch did not exist remotely yet. In GitHub's web interface, you should now see this branch listed under "branches".
9. Switch back to the main branch by running git checkout main
10. Merge the changes you made in the practice branch into the main branch by running git merge practice
11. Push to the remote repository.

Log of Commit Messages

1. Finally, run git log to see the history of commit messages.

Just the Beginning

We have just scratched the surface of what you can do with Git, but it's a good start. Later, we will use Git to help us collaborate with other students and improve our workflow.

Use Git smartly, by regularly and intelligently committing your code. Commit when you have completed (written, tested, documented) some feature or when you've fixed a bug.

Practice more using Learn Git Branching may help -- you probably just need Main: Introduction Sequence and Remote: Push & Pull -- Git Remotes

Submitting your assignment

If you followed the above directions, you will have "submitted" your assignment by putting the required files in the repository. I can only grade what has been pushed to the GitHub repository. You can look at your repository through GitHub's web interface to confirm that all the required files are there.

Grading

You will be evaluated based on the contents of your repository on GitHub (30 pts):

• myfile.txt in the repository with the required text
• About.md updated with the required text
• At least three descriptive commit messages in the log
• practice branch in GitHub repository
• Changes from practice branch merged into main branch