Skip to main content.

Git Lab: Gitting--er, Getting Started

Due Monday before 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 since 1972, 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

Git Resources

Reference these resources to help you use Git

Part 0: GitHub Classroom

  1. Go to the assignment invitation
  2. Select your email address.
  3. Accept the Git & GitHub Fundamentals assignment. This will create your own private repository for the assignment that you and I can see.

Part 1: Practicing Git

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
  4. Enter your GitHub username and your access token for the password.

    (On Macs, you'll see a key when it prompts for the password. Enter your personal access token. You won't see any typing -- that's a security feature. Just enter your token and hit enter.)

    This should create a directory with the repository in the current directory, i.e., you should now see a directory with the name something like git-and-github-fundamentals-username. Within that directory is your repository. (What Unix commands should you use to check that this is the case.)

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

  5. Go into your repository directory. List the contents of the directory.

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. Back on your computer, open README.md in your favorite text editor. Compare the contents of the file to what is displayed. For example, 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. Back in your browser, read the README.md file to learn about Git and GitHub.

    In general, a README file (regardless of the file extension, e.g., .md, or .txt) gives a user information about software. We'll also use the README file to help us communicate between student(s) and professor.

Create and Add Files in Your Local Repository

Recall: When we say local repository, that means local to your computer. Remote means the one on GitHub.

  1. Create a new file called myfile.txt within your cloned/local repository. (Recall: where is your repository?) You can create this file using whatever text editor you like, e.g., jEdit, Atom, VSCode, emacs, vim, nano, even Idle.
  2. Within the file, write, "This is my first file for my repository." Save the file.
  3. In your shell/terminal, make sure that you are within your repository (i.e., you're within the directory where your repository is stored), and then add the file to your repository by running
    git add myfile.txt
  4. 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.

  1. Run git commit
    This will commit the files you staged, i.e. the files you added to the staged area.
    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.

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

  1. Run git push to push the local repository to the remote repository.
  2. You should 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.

  1. 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. Save it within your local repository.
  2. Under that heading, write your name with your class year, e.g., "Sara Sprenkle, 1999". Save the file.
  3. Add a level 2 heading (using two "#"s) that says "Honor Pledge"
  4. 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.
  5. 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.
  6. 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 does 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.
  12. Again, you should check the remote repository through the GitHub web interface to confirm that everything is there.

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