Skip to main content.

Git Lab: Gitting--er, Getting Started

Due 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 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 version 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 comfortable/confident in your version control skills.

Objectives

Git Resources

Part 0: Set up Your GitHub Account

Create a personal access token (classic) in the GitHub web interface.

GitHub is encouraging use of their new fine-grained access tokens, which are more secure. However, they are still in beta and not supported by all of GitHub's tools yet, and GitHub hasn't made them quite as easy/intuitive to use. We may use these later in the semester, but, for now, let's stick with the classic ones.

Part 1: GitHub Classroom

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

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

    It is not recommended to put your repositories in a location that is synched, e.g., Box, Google Drive, One Drive. Instead, put your repositories on your local hard drive. It may not be a problem if you don't try to access the synched folders on another computer, but safest not to try. Git has its own approach to backups.

  2. In GitHub classroom, copy the https repository URL from under the "Code" button dropdown.
  3. Run the command:
    git clone your_repository_URL
  4. Enter your GitHub username and your access token, which you created in the set up assignment, 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-started--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.

Part 3: Learn Git and GitHub

  1. In your web browser, go to your GitHub repository for this assignment. The README.md file is rendered and displayed below the top-level source code listing.
  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 in the file?

    The .md extension means that it is a Markdown file. Markdown is a commonly used markup language to add formatting to text documents. It's used to make pretty documents for the Web easily. Markdown is rendered into HTML 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. In this course, we'll use the README file to help us communicate between student(s) and professor.

Part 4: Learning git with an online tutorial

In your browser, go to Learn Git Branching It's a helpful game to learn git, but you need to be thoughtful and mindful while doing it so that you understand what is happening. Pay attention to the visuals.

Run through the tutorial/game "Main > Introduction Sequence" and "Ramping Up". Then click on the tab "Remote" and complete the series "Push & Pull -- Git Remotes!"

Part 5: Applying What You Learned

Create and Add Files in Your Local Repository

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

  1. In a terminal, go into your cloned, local repository.
  2. 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, emacs, Pulsar, VSCode, vim, nano, even Idle. The important part is that the file is saved within your cloned, local repository.
  3. Within the file, write, "This is my first file for my repository." Save the file.
  4. 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
  5. 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."

    Alternatively, you can use the -m flag (i.e., for message) and add a comment, e.g.,
    git commit -m"Created a new file to try out git."

    If you run into trouble because the default editor is vim and you aren't sure how to use it, first hit i to go into insert mode. Then, 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 Git Setup and update the editor being used.
    If you're seeing errors like command not found, it's likely that your text editor for git 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 (i.e., in a web browser) 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?

    If it's not rendered correctly, edit your file to make sure you have spaces after the headings.

Expected Rendering of About.md (Approximate):

About Me

Sara Sprenkle, 1999

Honor Pledge

On my honor, I have neither given nor received any unacknowledged aid on this lab.

Sara Sprenkle

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, which you can confirm by using git status
  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.

Part 6: Creating Your Profile on GitHub

Create your profile README. Let everyone know a little bit more about you! What are you interested in learning? What are you working on? What's your favorite hobby? This is pretty open -- I just want you to take advantage of some of the advantages of using GitHub.

You can see my profile readme, which is quite simple.

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 strategically committing your code. Commit when you have completed (written, tested, documented) some feature or when you've fixed a bug.

As you get used to git, you should return to Learn Git Branching to practie/solidify your knowledge and learn more advanced techniques.

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