7.1: Git

Learning Objectives

By the end of this lesson, you should be able to:

1. Explain what Version Control is..

2. Briefly explain what Git is, and why it is used.

3. Be familiar with common git commands.

4. Initialise a Git repository and make commits.

5. Refer to the Git Cheat Sheet when needed.

Introduction

Before following along, make sure you have your git settings setup correctly as per Required Software. Ask in your section slack channel if you are unsure about any settings. Ensure that the default branch name for a new git repository is main and not master, by setting:

git config --global init.defaultBranch main

This will help us avoid problems when working with GitHub later. You can input this command more than once with no adverse effects, so you can always re-type it to be sure, or check all global settings:

git config -l

You can read more about why GitHub recently changed their default branch name from master to main here.

Version Control

Version control is a system that allows us to track changes over the lifetime of a file. A system like this isn't limited to code, and isn't limited to text files. It could be used for video files or other assets, or other text files such as contracts or articles.

The system of version control is a fundamental part of being a software engineer, and of developing a complex software project. In this course we'll use version control to keep track of our work, and submit our assignments using the web app GitHub.

Git

Git is the most popular version control system for developers, and the version control system we'll be using. It was invented by the same person who invented Linux, to help coordinate large complex software projects between distributed teams of engineers.

In SWE Fundamentals we'll be learning Git so that we can keep track of different versions of our code. In 8.2 (GitHub Repo Browsing) we'll cover how to browse and get back these older versions, but in this section we'll only cover some basic actions within Git and how to record the versions of our code in the first place.

Don't worry if some of the version control concepts are hard to understand now, we'll slowly be expanding our use and knowledge of Git as the course goes along. Git is not programming so it's simply a tangential tool to help as the code becomes harder to build and keep track of.

Why Do We Need Git?

In order to do programming it's not strictly necessary to use Git or any version control. We want to use it mainly because, even though there is a lot of overhead for understanding the command line interface and learning the basic Git concepts, we want to eliminate the fear of breaking a given set of code. As we'll soon see, the main task of programming is to incrementally build up code that will inevitably have errors. One of the main uses of version control (for all programmers, not only in SWE Fundamentals) is to make sure that introducing a new error is not catastrophic. When all new small changes are carefully saved in Git versions, we can be sure that whatever new code we try won't result in an unfixable error.

Git Terminology

Parts of a Git repository

Repository

A core concept in Git is the "Repository", or "Repo" for short. This is a folder that holds all the code for one project.

Commits

A Git Repo consists of a time series of commits in the order that they were recorded in the Git system. A commit contains a set of changes to one or more files. These changes can be changes to contents of a file, but also include addition of a new file, deletion of a file, or renaming or moving a file.

Staging

With Git, changes need to be staged before they can be committed. Staging is useful for when we may wish to make multiple commits out of the changes we have made locally. We can choose which changes go in which commit by staging the files we wish to add to each commit before running the commit command. For example, if I've changed files A and B for features A and B respectively, I could first stage only A and commit A, then stage only B and commit B. I would then have 2 independent commits for A and B that I could inspect or revert independently.

Git Commands

In this course we'll be using the command line to manipulate Git. There are other ways to manipulate Git, including several GUI applications, but the command line is the most canonical and widely-used way to manipulate Git.

init

git init

git init is the command to create a new Git repository. We will not be using this command in SWE Fundamentals because we download starter code with git clone.

Creating a repo inside a repo can cause problems. If we are in the command line and running git status doesn't throw an error, we are already inside a Git repo. Don't do git init or git clone in this directory.

status

git status

git status is the command to see the current status of the repo. This is typically used to see which files are "staged for commit" in green, and which files are "not staged for commit", in red. To be staged means that if we were to run git commit at that moment, the changes to the staged files would be included in the commit.

Example of git status output. script.js is "not staged for commit".

diff

git diff is the command that shows the changes made within a given file or directory.

git diff <path>

Often our changes will be longer than the terminal window height, and git diff will open a special menu to navigate these changes. To exit this menu, use q, as suggested in 1.3: Command Line's Troubleshooting section.

add

git add is the command that stages files for commits. Staging is a label for a group of files, where all "staged" files will be included in the next commit. git status will show us which files are staged and not staged. Staged files will appear in green, and files that have not been staged, in red. In Git, creating a commit happens in 2 steps.

1. At least one file is labeled as "staged" with the add command.

2. A commit is created that includes the staged files with the commit command

git add <path>

commit

git commit creates the commit record in the repo. We must use the -m option to include a "commit message", a short sentence about what we changed. Commit messages typically include what was changed and why a change was made.

git commit -m "message that describes the changes"

Running git commit without -m might bring you into the vi editor. If you get stuck in vi type Esc and :q!, followed by Enter to get out.

vi looks like the following.

The first time you make a Git commit you may encounter an error asking you to run the following commands:

git config --global user.name "First Name Last Name"
git config --global user.email "[e-mail]"

This is normal. Git is asking us to set our Git identity so that any commits we make are tied to our name and email. Once you run those commands, you should be able to make commits as expected.

log

Finally, to see a list of the commits in this repo (including the one you just created) use git log

git log

Eventually our list of commits will be longer than the terminal window height, and git log will open a special menu to navigate this list. To exit this menu, use q, as suggested in 1.3.: Command Line's Troubleshooting section.

Cheat Sheet

Create a Git repo

git init

Check repo status, e.g. which files are staged

git status

View changes in unstaged files

git diff

Mark file(s) as "staged" to prepare them for commit

git add <FILE_NAME>

Create a commit with currently-staged files

git commit -m "fixed spelling error"

View past commits

git log

Git version control is a deep topic. We are only covering a tiny portion of all the Git functionality in SWE Fundamentals to give a small look into the world of developer workflow and version control. This will be a tool that we hope will be valuable in your coding later in the course. Don't worry if you don't understand everything! We'll also see more about Git later in module 8.

Exercises

You may wish to refer to the command line cheatsheet and Git cheatsheet, and use window snapping to position 3 windows on your screen simultaneously: VSCode, the relevant cheatsheet, and these instructions.

Create a Haiku

We will create poetry, save and edit it using the command line and Git.

1. Open the command line and create a folder for our poetry using mkdir.

2. cd into the folder, and initialise it as a git repo using git init

3. Create a text file in the command line using touch haiku.txt and open it in VSCode with the command code haiku.txt

4. Write a haiku about trees in the text file and save the file. A haiku is a Japanese poem that follows the convention of 5 syllables, 7 syllables, and 5 syllables on each of 3 lines respectively.

   1. If writing poetry is difficult, feel free to make up something :) The content isn't particularly important for this exercise.

5. Stage and commit your new text file.

6. Edit our poem to reference leaves. Make a commit for our changes.

7. Add a 2nd poem about winter in another file. Commit this file to the repo.

8. Add a title to our poem about trees. Add the title above the text in the file, and change the filename to reflect the title. Note here that we can change more than one file, and only stage the trees file for committing. In this way we can say which files go into a given commit. Don't stage or commit the winter poem.

9. Use git log to see the change log of the current repository.

Hint: When typing in the command line we can press the tab key and the command line will try to auto-complete the current command, file, or folder name. This can help reduce unnecessary typing and typos

Committing and Tracking Changes to Project 1

Navigate to your Scissors Paper Stone directory, and initialize it as a git repo. Make your first commit with a meaningful, but brief message describing your current progress on the project. As you continue adding to the project, make meaningful commits at each checkpoint. Approach your Section Leader if you have any questions. When we learn how to use and navigate GitHub, we will be able to visualize our progress, and travel through time via these commits.