Lab 0: Gitting--er, Getting Started

Due before Wednesday's class

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 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

Due: Before the next class (Wednesday).

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"
```
Commit messages automatically open an editor to write/save the 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.

Get a GitHub Account

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

GitHub Classroom

Go to the emailed 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

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

Create and Add Files in Your Local Repository

Create a new file called myfile.txt in the location where you cloned your 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.
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 master
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 promted 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. Go back to the Set Up step and update the editor being used.

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

On branch master
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 update the README.md file. In general, a README file gives a user information about software. We'll also use the README file to help us communicate student to teacher. 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.

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.
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?
Using your favorite text editor, edit README.md so that it contains a Level 2 heading (using two "#") 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 another 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 README.md to the staging area, commit the changes with a descriptive message, and push the commit to the remote repository.

Creating and Merging a Branch

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

Create a branch by running git branch practice. You are still in the master branch at this point.
Switch to the practice branch by running git checkout practice
Run git status to confirm that you're on the practice branch.
Update the README.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.)
Update the myfile.txt file to add another line that says "Please look at the README file."
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.
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".
Switch back to the master branch by running git checkout master
Merge the changes you made in the practice branch into the master branch by running git merge practice
Push to the remote repository.

Log of Commit Messages

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
README.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 master branch