Introduction to Git¶

Git is a system used for developing software in a group. In a nutshell, Git is a version control system that maintains files in a repository that contains not just files, but also a record of all the changes made to those files. Git tracks every version of a file or directory using commits. When you have made changes to one or more files, you can logically group those changes into a “commit” that gets added to your repository. You can think of commits as “checkpoints” in your work, representing the work you’ve done since the previous checkpoint. This mechanism makes it possible to look at and even revert to older versions of a file by going back to your code as it was when you “checkpointed” it with a commit.

You will each have a set of personal Git repositories, one per assignment, that will be hosted on a central server.

This tutorial provides an introduction to various aspects of Git. All you need to do is follow the instructions. Please do make sure you understand what is accomplished in each step and, if you have any questions, please don’t hesitate to ask for help.

Where should you do this tutorial?¶

Like the Linux tutorial, we will specifically need you to work on a CS machine, which means you will either have to work in CSIL or connect remotely using a using a virtual desktop.

However, now that you’re familiar with the Linux terminal, you have one additional option: connecting to a CS server using SSH. This will allow you to open a CS command-line terminal from your own computer. The CS techstaff provides detailed instructions on how to do this.

Throughout this tutorial, you will have to make some simple edits to a few text files. If you are using SSH, we suggest you use a command-line editor for editing (like Vi, emacs, nano, etc.), or Ubuntu’s built-in Text Editor if you are in CSIL or using the Virtual Desktop. You do not need to use a full-featured code editor in this tutorial.

Getting started¶

In the course’s Ed Discussion site (which you can reach through Canvas), we have supplied a few URLs that you will need as you work through this tutorial.

For each assignment, a Git repository will be created for you on GitHub, a web-based hosting service for Git repositories. However, before that repository can be created for you, you need to have a GitHub account. If you do not yet have one, you can get an account here: https://github.com/join. Once you create your account, you may want to get the Student Developer Pack, which will give you access to a lot of other features (please note that having the Student Developer Pack is not necessary for CMSC 12100; it’s just a nice benefit you get as a student.)

Creating an SSH Key¶

When you log into the GitHub website, you will use the username and password associated with your GitHub account. However, when using Git commands from the terminal, things are a bit different. In particular, GitHub uses two mechanisms for authenticating yourself from the terminal: Personal Access Tokens and SSH Keys. We will be using SSH keys.

In a nutshell, an SSH key is a file that resides in your home directory, and which you can think of as a file that stores a secure password (SSH keys are a bit more complex than that but, for our purposes, we can just think of them as extra-secure passwords)

To create an SSH key, run the following command from the terminal:

$ ssh-keygen

You will see the following prompt:

Generating public/private rsa key pair.
Enter file in which to save the key (/home/username/.ssh/id_rsa):

Press Enter (this will select the default file path shown in the prompt: /home/username/.ssh/id_rsa

Note

If, after pressing Enter, you see the following message:

/home/username/.ssh/id_rsa already exists.
Overwrite (y/n)?

This means there is already an SSH key in your home directory. You should proceed as follows:

If you are already familiar with SSH keys, and know for certain that you’d like to use your existing SSH key, type “n” and skip ahead to the “Uploading your SSH key to GitHub” section below.
If you do not know why you have an SSH key in your directory, it’s possible it was created for you if you’ve taken another CMSC class in the past. Type “n” and then run the following commands to create a backup of your existing key:
```
mv ~/.ssh/id_rsa ~/.ssh/id_rsa.bak
mv ~/.ssh/id_rsa.pub ~/.ssh/id_rsa.pub.bak
```
Then, re-run the ssh-keygen command, press Enter when prompted for the file name, and follow the rest of the instructions in this section.

Next, you will see this prompt:

Enter passphrase (empty for no passphrase):

Just press Enter here. You will be asked to confirm (just press Enter again):

Enter same passphrase again:

Note

While it may seem counterintuitive, we don’t want our SSH key to have a passphrase (this is an added layer of security which we won’t need for this class; your GitHub account will still be secure even if your SSH key doesn’t have a password)

If all goes well, you should see something like this:

Your identification has been saved in /home/username/.ssh/id_rsa
Your public key has been saved in /home/username/.ssh/id_rsa.pub
The key fingerprint is:
SHA256:cBUUs2FeMCIrBlTyv/PGpBtNz0v235zvLykpoWIOS9I username@machine
The key's randomart image is:
+---[RSA 3072]----+
| .+.. . ..@+.    |
|   +   o = *     |
|    + o . o      |
|   . o o         |
|      . S        |
|   .   +.o.      |
|  . E ++..=. . . |
|   o o+++o.oo oo.|
|    .oo+. ...o.+O|
+----[SHA256]-----+

This means your key was created correctly.

Uploading your SSH key to GitHub¶

Now, we need to instruct GitHub to accept our SSH key. To do this, log into https://github.com/ and go to your Settings page (by clicking on the top-right account icon, and then selecting “Settings” in the drop-down menu. Then, click on “SSH and GPG keys”.

Now, click on the green “New SSH key” button. This will take you to a page where you can upload your SSH key. You will be asked for two values: a “Title” and the key itself. The title can be anything you want, but we suggest something like “CS 121 SSH Key”.

The value of the key is contained in the .ssh/id_rsa.pub file in your home directory. To print out the contents of that file, we can just use the cat command, which we covered in the Linux tutorial:

$ cat ~/.ssh/id_rsa.pub

This will print a few lines of output starting with ssh-rsa and ending in something like username@machine. Copy the whole output to the clipboard; you can do this by clicking and dragging the mouse from the first character to the last character, and then pressing Ctrl-Shift-C.

Then, paste the key into the “Key” field on the GitHub page. Then click on the green “Add SSH Key” button.

To verify that you correctly uploaded the key, try running the following command:

ssh -T git@github.com

You may see a message like this:

The authenticity of host 'github.com (...)' can't be established.
RSA key fingerprint is SHA256:nThbg6kXUpJWGl7E1IGOCspRomTxdCARLviKw6E5SY8.
Are you sure you want to continue connecting (yes/no)?

You can safely enter “yes” here. You should then see a message like this:

Hi username! You've successfully authenticated, but GitHub does
not provide shell access.

This means your SSH key is properly set up (don’t worry about the “does not provide shell access”; that is normal).

If you are unable to set up your SSH key, please make sure to ask for help. You will not be able to complete the rest of the tutorial until you’ve set up your SSH key.

If you would like to set up SSH access from your personal computer at a later time, GitHub provides some pretty detailed documentation on how to do this in a number of different operating systems: Connecting to GitHub with SSH Please note that we may not be able to assist you with SSH issues on your own computer.

Creating your first repository¶

For each assignment in CMSC 12100, we will provide you with an invitation URL that will allow you sign up for the assignment on GitHub and which will result in the creation of a repository called XX-GITHUB_USERNAME inside our uchicago-cmsc12100-aut-21 organization on GitHub. For example, if your GitHub username is jrandom and XX is tutorial-git, your repository will be called tutorial-git-jrandom. This repository will be private, and can only be viewed by you and the CMSC 12100 course staff.

For this tutorial, use the Git Tutorial URL that we supplied on Ed Discussion. When you open the invitation URL in a browser tab, you will have to complete the following steps:

You will need to select your name (and CnetID) from a list. This step will allow us to know what student is associated with each GitHub account. This step is only done for the very first assignment invitation you accept.
You must click “Accept this assignment” or your repository will not actually be created.

If you run into any issues, please ask for help.

Initializing your repository¶

You will start by initializing your repository. Your repository is hosted on GitHub, but you can create a local copy in your home directory (we will refer to this as your local repository).

Log into https://github.com/. Your homework repository, uchicago-cmsc12100-aut-21/tutorial-git-GITHUB_USERNAME should appear under “Repositories” on the left side of the page. (If you don’t see a list of repositories on the left side of the page, try clicking on the GitHub Cat logo.) Clicking on this link will take you to a page where you can browse your repository through GitHub’s web interface. Since you haven’t initialized your repository yet, GitHub will provide you with the instructions to initialize your repository. You can ignore those instructions. Instead, do the following:

We’re going to run several commands that refer to your GitHub username. To make sure your username is included correctly in those commands, we’re going to define a “shell variable” to store your username. Just run the following in the terminal, and take care to replace replace_me with your GitHub username:
```
GITHUB_USERNAME=replace_me
```
To verify that the variable was set correctly, run the following:
```
echo $GITHUB_USERNAME
```
If this command prints out (literally) replace_me (or anything other than your GitHub username), then the variable was not properly set. Make sure to re-run the GITHUB_USERNAME=replace_me command and remember that you have to replace replace_me (and only replace_me) with your GitHub username.

Note: This variable will only exist in your current terminal. If you open a new terminal, you will need to rerun the command to create the GITHUB_USERNAME variable.
In the Linux Tutorial, we created a cmsc12100 directory. Make sure you are inside that directory; this will ensure that all your CS 121 files are all under the same directory. That said, the name and location of this directory is not important, so if you have a very strong preference for a different directory structure, you’re welcome to use it. Otherwise, we suggest you simply do this:
```
cd
mkdir -p cmsc12100/tutorial-git-$GITHUB_USERNAME
cd cmsc12100/tutorial-git-$GITHUB_USERNAME
```
Notice how we’re using the GITHUB_USERNAME variable we defined earlier. When you run the above commands, the terminal will automatically replace the text $GITHUB_USERNAME with your GitHub username.

The -p flag to mkdir will create all the parent directories if needed; i.e., if you don’t already have a cmsc12100 directory, it will create one, and then will create a tutorial-git-GITHUB-USERNAME directory inside it.
Navigate to the folder you just created, create a file called README.md, and add your full name to the file using an editor. You can create a new file using VSCode by running code <filename> in a terminal window that is the opened in appropriate directory. (Recall that the notation <filename> is a placeholder that should be replaced with an actual filename.) For this specific task, can use the command code README.md.
Run the following commands. You don’t need to understand what these commands do (we will explain them later on):
```
git init
git add README.md
git commit -m "first commit"
git branch -M main
```
At this point, your cmsc12100/tutorial-git-GITHUB-USERNAME directory has been initialized as a Git repository, and we have added the README.md file to it.
Now, we need to “connect” your repository to the one on GitHub. To do this, run the following command:
```
git remote add origin git@github.com:uchicago-cmsc12100-aut-21/tutorial-git-$GITHUB_USERNAME.git
```

Finally, we are going to upload our local Git repository to GitHub. We will do so by running this:

git push -u origin main

You should see something like this:

$ git push -u origin main
Enumerating objects: 3, done.
Counting objects: 100% (3/3), done.
Writing objects: 100% (3/3), 232 bytes | 232.00 KiB/s, done.
Total 3 (delta 0), reused 0 (delta 0)
To github.com:uchicago-cmsc12100-aut-21/tutorial-git-username.git
 * [new branch]      main -> main
Branch 'main' set up to track remote branch 'main' from 'origin'.

If the command fails, a likely cause is an issue with your SSH key. Please make sure to ask for help before proceeding.

Again, don’t worry about what each individual command does; we will be seeing what most of these commands do in this tutorial. If you encounter any error messages, please do make sure to let us know.

You can verify that your repository was correctly set up by going back to your repository’s page on GitHub, you should now see it contains a README.md file. If you click on it, you can see its contents.

Creating a commit¶

If you make changes to your repository, the way to store those changes (and the updated versions of the modified files) is by creating a commit. So, let’s start by making some changes:

Edit README.md to also include your CNetID on the same line as your name
Create a new file called test.txt that contains a single line with the text Hello, world!

Creating a commit is a two-step process. First, you have to indicate what files you want to include in your commit. Let’s say we want to create a commit that only includes the updated README.md file. We can specify this operation explicitly using the git add command from the terminal:

git add README.md

This command will not print any output if it is successful.

To create the commit, use the git commit command. This command will take all the files you added with git add and will bundle them into a commit:

git commit -m "Updated README.md"

The text after the -m is a short message that describes the changes you have made since your last commit. Common examples of commit messages might be “Finished homework 1” or “Implemented insert function for data struct”.

Warning

If you forget the -m parameter, Git will think that you forgot to specify a commit message. It will graciously open up a default editor so that you can enter such a message. This can be useful if you want to enter a longer commit message (including multi-line messages). We will experiment with this later.

Once you run the above command, you will see something like the following output:

[main 3e39c15] Updated README.md
 1 file changed, 1 insertion(+), 1 deletion(-)

You’ve created a commit, but you’re not done yet: you haven’t uploaded it to GitHub yet. Forgetting this step is actually a very common pitfall, so don’t forget to upload your changes. You must use the git push command for your changes to be uploaded to the Git server. If you don’t, the course staff will not be able to see your work. Simply run the following command from the Linux command-line:

git push

You may be asked for your GitHub username and PAT; once you enter them, you should see something like this output:

Enumerating objects: 5, done.
Counting objects: 100% (5/5), done.
Writing objects: 100% (3/3), 279 bytes | 279.00 KiB/s, done.
Total 3 (delta 0), reused 0 (delta 0)
To git@github.com:uchicago-cmsc12100-aut-21/tutorial-git-GITHUB-USERNAME
   392555e..0c85752  main -> main

You can ignore most of those messages. The important thing is to not see any warnings or error messages.

Warning

When you push for the first time, you may get a message saying that push.default is unset, and suggesting two possible commands to remedy the situation. While the rest of the commands in this homework will work fine if you don’t run either of these commands, you should run the command to use “simple” (this will prevent the warning from appearing every time you push)

You can verify that your commit was correctly pushed to GitHub by going to your repository on the GitHub website. The README.md file should now show the updated content (your name and CNetID)

In general, if you’re concerned about whether the course staff are seeing the right version of your work, you can just go to GitHub. Whatever is shown on your repository’s page is what the course staff will see. If you wrote some code, and it doesn’t show up on GitHub, make sure you didn’t forget to add your files, create a commit, and push the most recent commit to the server.

`git add` revisited and `git status`¶

Let’s make a further change to README.md: Add a line with the text CMSC 30121 - Computer Science with Applications 1.

So, at this point, we have a file we have already committed (README.md) but where the local version is now out of sync with the version on GitHub. Furthermore, earlier we created a test.txt file. Is it a part of our repository? You can use the following command to ask Git for a summary of the files it is tracking:

git status

This command should output something like this:

On branch main
Your branch is up to date with 'origin/main'.

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
    modified:   README.md

Untracked files:
  (use "git add <file>..." to include in what will be committed)
    test.txt

no changes added to commit (use "git add" and/or "git commit -a")

Note

When working on CS machines, you should see the message above. At some point, you will start using git with your own machine. depending on the version of Git you have installed, the message under Changes not staged for commit may refer to a command called git checkout (instead of git restore).

Notice that there are two types of files listed here:

Changes not staged for commit: This is a list of files that Git knows about and have been modified since your last commit, but which have not been added to a commit (with git add). Note that we did use git add previously with README.md (which is why Git is “tracking” that file), but we have not run git add since our last commit, which means the change we made to README.md is not currently scheduled to be included in any commit. Remember: committing is a two-step process (you git add the files that will be part of the commit, and then you create the commit).
Untracked files: This is a list of files that Git has found in the same directory as your repository, but which Git isn’t tracking.

Warning

You may see some automatically generated files in your Untracked files section. Files that start with a pound sign (#) or end with a tilde should not be added to your repository. Files that end with a tilde are backup files created by some editors that are intended to help you restore your files if your computer crashes. In general, files that are automatically generated should not be committed to your repository. Other people should be able to generate their own versions, if necessary.

So, let’s go ahead and add README.md:

git add README.md

And re-run git status. You should see something like this:

On branch main
Your branch is up to date with 'origin/main'.

Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
    modified:   README.md

Untracked files:
  (use "git add <file>..." to include in what will be committed)
    test.txt

Note

When working on CS machines, you should see the message above. When using your git on own machine and depending on the version of Git you have installed, the message under Changes to be committed may refer to a command called git reset (instead of git restore).

Notice how there is now a new category of files: Changes to be committed. Adding README.md not only added the file to your repository, it also staged it into the next commit (which, remember, won’t happen until you actually run git commit).

If we now add test.txt:

git add test.txt

The output of git status should now look like this:

On branch main
Your branch is up to date with 'origin/main'.

Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
    modified:   README.md
    new file:   test.txt

Now, we are going to create a commit with these changes. Notice how we are not going to use the -m parameter to git commit:

git commit

When you omit -m, Git will open a terminal text editor where you can write your commit message, including multi-line commit messages. By default, the CS machines will use nano for this. You should see something like this:

# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
#
# On branch main
# Your branch is up to date with 'origin/main'.
#
# Changes to be committed:
#       modified:   README.md
#       new file:   test.txt
#

Now, type in the following commit message above the lines that start with #:

Git Tutorial updates:

- Added test.txt
- Updated README.md file

In nano, you can save the file and exit by pressing Control-X, entering “Y” when prompted to “save modified buffer” (i.e., whether to save the file before exiting), and then Enter (you may be presented with a new set of menu options; just press Enter).

This will complete the commit, and you will see a message like this:

[main 1810c54] Git Tutorial updates:
 2 files changed, 3 insertions(+), 1 deletion(-)
 create mode 100644 test.txt

Note

If you want to change your default command-line editor, add a line like this:

export EDITOR=myfavoriteeditor

At the end of the .bashrc file in your home directory (make sure you replace myfavoriteeditor with the command for your favorite command-line editor: vi, emacs, nano, mcedit, etc.)

Now, edit README.md and test.txt and add an extra line to each of them with the text Git is pretty cool. Running git status should now show the following:

On branch main
Your branch is ahead of 'origin/main' by 1 commit.
  (use "git push" to publish your local commits)

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
    modified:   README.md
    modified:   test.txt

If we want to create a commit with these changes, we could simply run git add README.md test.txt, but this can get cumbersome if we want to add a lot of files. Fortunately, we can also do this:

git add -u

This command will add every file that Git is tracking, and will ignore untracked files. There are a few other shortcuts for adding multiple files, like git add . and git add --all, but we strongly suggest you avoid them, since they can result in adding files you did not intend to add to your repository.

So, if you run git add -u and create a commit:

git commit -m "A few more changes"

git status will now show this:

On branch main
Your branch is ahead of 'origin/main' by 2 commits.
  (use "git push" to publish your local commits)

nothing to commit, working tree clean

The message Your branch is ahead of 'origin/main' by 2 commits. is telling you that your local repository contains two commits that have not yet been uploaded to GitHub. In fact, if you go to your repository on the GitHub website, you’ll see that the two commits we just created are nowhere to be seen. As helpfully pointed out by the above output, all we need to do is run git push, which should show something like this:

Enumerating objects: 10, done.
Counting objects: 100% (10/10), done.
Delta compression using up to 16 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 728 bytes | 728.00 KiB/s, done.
Total 8 (delta 1), reused 0 (delta 0)
remote: Resolving deltas: 100% (1/1), done.
To git@github.com:uchicago-cmsc12100-aut-21/tutorial-git-GITHUB-USERNAME
   0c85752..e3f9ef1  main -> main

Now go to GitHub. Do you see the updates in your repository? Click on “Commits” (above the file listing in your repository). If you click on the individual commits, you will be able to see the exact changes that were included in each commit.

Now, git status will look like this:

On branch main
Your branch is up to date with 'origin/main'.

nothing to commit, working tree clean

If you see nothing to commit, working tree clean, that means that there are no changes in your local repository since the last commit you created (and, additionally, the above output also tells us that all our commits have also been uploaded to GitHub)

Working from multiple locations¶

So far, you have a local repository in your CS home directory, which you have been uploading to GitHub using the git push command. However, if you work from multiple locations (e.g., on a CS machine but also from your laptop), you will need to be able to create a local repository in those locations too. You can do this by running the git clone command (don’t run this command just yet):

git clone git@github.com:uchicago-cmsc12100-aut-21/tutorial-git-$GITHUB_USERNAME

This will create a local repository that “clones” the version of the repository that is currently stored on GitHub.

For the purposes of this tutorial, we’ll create this second copy in a separate directory of the same machine where you’ve been running Git commands so far. Open a second terminal window (try using the keyboard shortcut Ctrl+Alt+t. to create the window).

First, since we’re in a new terminal, we’ll need to define our GITHUB_USERNAME shell variable again. Remember you can do so like this, taking care to replace replace_me with your GitHub username:

GITHUB_USERNAME=replace_me

Next, run these commands in the new terminal:

mkdir -p /tmp/$USER/cmsc12100
cd /tmp/$USER/cmsc12100
git clone git@github.com:uchicago-cmsc12100-aut-21/tutorial-git-$GITHUB_USERNAME

Notice how there’s an additional shell variable involved: $USER. We don’t have to define this variable (like we did with GITHUB_USERNAME) because USER is an environment variable that is set automatically to your user name. Bash will replace $USER in the command with your CS login.

Take into account that, when you run git clone, the repository is not cloned into the current directory. Instead, a new directory (with the same name as the repository) will be created in the current directory, and you will need to cd into it to use Git commands for that repository.

You now have two local copies of the repository: one in your home directory (/home/USER/cmsc12100/tutorial-git-GITHUB-USERNAME), which refer to as your home repository for now and one in /tmp (/tmp/USER/cmsc12100/tutorial-git-GITHUB-USERNAME) which we will refer to as your temp repository.

Now, switch to the window that is open to your home repository, add a line to test.txt with the text One more change!. Create a commit for that change and push it to GitHub (you should know how to do this by now, but make sure to ask for help if you’re unsure of how to proceed). Also, you don’t have to use any specific commit message (unlike previous steps where we gave you the exact message), but make sure your commit message is descriptive and to the point.

Next, switch to the window that is open to your temp repository, check if that change appears in the test.txt file. It will not, because you have not yet downloaded the latest commits from the repository. You can do this by running this command:

git pull

This should output something like this:

remote: Enumerating objects: 5, done.
remote: Counting objects: 100% (5/5), done.
remote: Compressing objects: 100% (2/2), done.
remote: Total 3 (delta 0), reused 3 (delta 0), pack-reused 0
Unpacking objects: 100% (3/3), 312 bytes | 20.00 KiB/s, done.
From git@github.com:uchicago-cmsc12100-aut-21/tutorial-git-GITHUB-USERNAME
   e3f9ef1..5716877  main       -> origin/main
Updating e3f9ef1..5716877
Fast-forward
 test.txt | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

If you have multiple local repositories (e.g., one on a CS machine and one on your laptop), it is very important that you remember to run git pull before you start working, and that you git push any changes you make. Otherwise, your local repositories (and the repository on GitHub) may diverge leading to a messy situation called a merge conflict (we discuss conflicts in more detail below). This will be specially important once you start using Git for its intended purpose: to collaborate with multiple developers, where each developer will have their own local repository, and it will become easier for some developers’ code to diverge from others’.

Discarding changes and unstaging¶

One of the benefits of using a version control system is that it is very easy to inspect the history of changes to a given file, as well as to undo changes we did not intend to make.

For example, edit test.txt to remove all its contents. Make sure you do this in your home repository (/home/USER/cmsc12100/tutorial-git-GITHUB-USERNAME) and not in the temp repository you created earlier.

git status will tell us this:

On branch main
Your branch is up to date with 'origin/main'.

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
    modified:   test.txt

If we want to discard the changes we made to test.txt, all we have to do is follow the helpful advice provided by the above output:

git restore test.txt

Note

In older versions of Git, git status may refer to the git checkout command. In that case, run this command instead:

git checkout -- test.txt

If you open test.txt, you’ll see that its contents have been magically restored!

Now, edit test.txt and README.md to add an additional line with the text Hopefully our last change.... Run git add -u but don’t commit it just yet. git status will show this:

On branch main
Your branch is up to date with 'origin/main'.

Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
    modified:   README.md
    modified:   test.txt

Now, let’s say we realized we want to commit the changes to README.md, but not to test.txt. However, we’ve already told git that we want to include test.txt in the commit. Fortunately, we can “un-include” it (or “unstage” it, in Git lingo) by running this:

git restore --staged test.txt

Note

In older versions of Git, git status may refer to the git reset command. In that case, run this command instead:

git reset HEAD test.txt

Now, git status will show the following:

On branch main
Your branch is up to date with 'origin/main'.

Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
    modified:   README.md

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
    modified:   test.txt

Go ahead and run git commit. The commit will now include only README.md.

Before moving on to the next part of the tutorial, let’s make sure all our changes have been committed and pushed:

git add -u
git commit -m"Wrapping up staging part of the tutorial"
git push

Before continuing, make sure git status shows this:

On branch main
Your branch is up to date with 'origin/main'.

nothing to commit, working tree clean

Looking at the commit log¶

Once you have made multiple commits, you can see these commits, their dates, commit messages, author, etc. by typing git log. This command will open a scrollable interface (using the up/down arrow keys) that you can get out of by pressing the q key. As we saw earlier, you can also see the history of commits through on GitHub’s web interface, but it is also useful to be able to access the commit log directly from the terminal, without having to open a browser.

Each commit will have a commit hash (usually referred to as the commit SHA) that looks something like this:

9119c6ffcebc2e3540d587180236aaf1222ee63c

This is a unique identifier that we can use to refer to that commit elsewhere. For example, choose any commit from the commit log and run the following:

git show COMMIT_SHA

Make sure to replace COMMIT_SHA with a commit SHA that appears in your commit log.

This will show you the changes that were included in that commit. The output of git show can be a bit hard to parse at first but the most important thing to take into account is that any line starting with a + denotes a line that was added, and any line starting with a - denotes a line that was removed.

Pro tip: in any place where you have to refer to a commit SHA, you can just write the first few characters of the commit SHA. For example, for commit 9119c6ffcebc2e3540d587180236aaf1222ee63c we could write just this:

git show 9119c6f

Git will only complain if there is more than one commit that starts with that same prefix.

Merge conflicts¶

If you have multiple copies of the same repository, it is easy for them to get out of sync. In this section, we will purposely create a merge conflict using the home and temp repositories that you have created to allow you to see how to fix conflicts. As in the section on working from multiple locations, you’ll want to have two windows open for this section: one where you’ll work with your home repository (that is, the copy of the repository in your home directory) and the other where you’ll work with your temp repository (the one in /tmp).

First, let’s add a file to your home repository. Use pwd to make sure you are in the right local copy the repository:

$ pwd
/home/USER/cmsc12100/tutorial-git-GITHUB-USERNAME

(USER will be your CNetID.) If the result of pwd starts with /tmp then you are in the wrong window and should switch to the correct one before proceeding.

Open an editor and create a file named balloons.py (code balloons.py) that contains these four lines of Python code:

print("Let's get started.")
print("How many red balloons were released?")
print("99 red balloons!")
print("All done.")

Now add, commit, and push this code to the server.

Switch to the window open to the temp copy of your repository and run ls. Do see balloons.py? No. Why? Because the temp copy of the repository is out of sync with the server. Run:

git pull

to get it back in sync.

To create a merge conflict, we need to edit files in different and conflicting ways. In the temp copy of the repository, replace both occurrences of red with green:

print("Let's get started.")
print("How many green balloons were released?")
print("99 green balloons!")
print("All done.")

Now add, commit, and push this code to the repository.

Switch back to the home copy of your repository (/home/$USER/cmsc12100/tutorial-git-$GITHUB_USERNAME). The home copy is out of sync with the server and the temp copy, but do not pull from the server to sync them up just yet. Instead, change red to blue in balloons.py:

print("Let's get started.")
print("How many blue balloons were released?")
print("99 blue balloons!")
print("All done.")

and then add and commit the file to this copy of your repository. If you try to push at this point, you’ll see a message like this:

$ git push
To git@github.com:uchicago-cmsc12100-aut-21/tutorial-git-GITHUB-USERNAME
! [rejected]        main -> main (fetch first)
error: failed to push some refs to 'git@github.com:uchicago-cmsc12100-aut-21/tutorial-git-GITHUB-USERNAME'
hint: Updates were rejected because the remote contains work that you do
hint: not have locally. This is usually caused by another repository pushing
hint: to the same ref. You may want to first integrate the remote changes
hint: (e.g., 'git pull ...') before pushing again.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.

The hint says to do a git pull, let’s try that:

$ git pull
Auto-merging balloons.py
CONFLICT (content): Merge conflict in balloons.py
Automatic merge failed; fix conflicts and then commit the result.

Git recorded the conflicts in balloons.py and it is our responsibility to resolve them before we proceed.

The file is small, so we can use cat to look at the contents:

$ cat balloons.py
print("Let's get started.")
<<<<<<< HEAD
print("How many blue balloons were released?")
print("99 blue balloons!")
=======
print("How many green balloons were released?")
print("99 green balloons!")
>>>>>>> 722bcb5b1b8e815f895f7256536f38e6d1a71c53
print("All done.")

The long number 722bcb5b1b8e815f895f7256536f38e6d1a71c53 is the SHA for our commit. You’ll see a different number there.

We need to resolve this conflict and remove the conflict markings (“<<<”, “===”, etc). In some cases, resolving the conflict will just involve editing the file to keep the exact code in one of the two versions. However, we are not required to do so. For example, the developer handling this merge conflict may look at this code and decide that red is the right color for the balloons after all. In that case, we would just replace the conflict with this code:

print("How many red balloons were released?")
print("99 red balloons!")

To make this change, open the file in an editor (code balloons.py) remove/update the relevant lines, and save your changes. When you are done, the file balloons.py should contain the following:

print("Let's get started.")
print("How many red balloons were released?")
print("99 red balloons!")
print("All done.")

Now, we need to tell Git that we’ve resolved the merge conflict. We do this by using git add:

git add balloon.py

Note how now git status recognizes that the merge conflict has been resolved, but has yet to be committed:

$ git status
On branch main
Your branch is ahead of 'origin/main' by 2 commits.
  (use "git push" to publish your local commits)

All conflicts fixed but you are still merging.
  (use "git commit" to conclude merge)

Changes to be committed:
    modified:   balloons.py

So, all we need to do is to run this command:

git commit

which will open up an editor with a default commit message like:

Merge branch 'main' of git@github.com:uchicago-cmsc12100-aut-21/tutorial-git-GITHUB-USERNAME into main

You could change this to something like Merging (balloons should actually be red) to indicate that you did not actually accept the changes from either version. For now you can leave it as it and just save the file. Once you save the commit message, the merge will be completed and you will see something like this:

[main 8e0f408] Merge branch 'main' of git@github.com:uchicago-cmsc12100-aut-21/tutorial-git-GITHUB-USERNAME into main

Before continuing with the rest of the tutorial, make sure to git push your work. You might also want to run git pull in your temp repo to bring it up to date with the server.

Working with upstream repositories¶

For each assignment, we provide some initial code that you must upload to your repository. We’ll use what is known as an upstream repository to distribute this code.

We have created a second assignment for you to gain practice with this process.

We’ll follow steps similar to what you did at the beginning of this tutorial with a couple of extra commands thrown in.

Using a browser, use the invitation URL we provide on Ed Discussion to create a new repository. Please note that you no longer have to select a CNetID, since GitHub will remember your selection from the previous repository you created.
We are once again going to rely on the existence of the GITHUB_USERNAME shell variable. Double-check that it is correctly set by running this:
```
echo $GITHUB_USERNAME
```
If this does not print out your GitHub username, run the following (replacing replace_me with your GitHub username):
```
GITHUB_USERNAME=replace_me
```
Navigate to your /home/$USER/cmsc12100 directory and creating a new directory named tutorial-git-upstream-$GITHUB_USERNAME.
```
cd ~/cmsc12100
mkdir tutorial-git-upstream-$GITHUB_USERNAME
cd tutorial-git-upstream-$GITHUB_USERNAME
```
Run this command to initialize a local repository:
```
git init
```
Now, run this command:
```
git remote add origin git@github.com:uchicago-cmsc12100-aut-21/tutorial-git-upstream-$GITHUB_USERNAME.git
```
This connects the local repository to the repository that was created for you on GitHub when you accepted the invitation.
Next, we’ll connect your local repository to an upstream GitHub repository that we have seeded with code for this assignment. Run this command:
```
git remote add upstream git@github.com:uchicago-cmsc12100-aut-21/tutorial-git-upstream.git
```
Now, run this:
```
git pull upstream main
```
This pulls the seed code from the upstream repository into your local copy of the repository and package it into a commit. Notice that the pull command indicates that code should be pulled from the main branch of the upstream repository.

At this point, if you run an ls, you will see that your directory now contains two files:
```
hello.py  README.md
```
Next, run this:
```
git branch -M main
```
This renames the default branch in your repository to main.
Finally, run this:
```
git push -u origin main
```
This pushed the current commit to GitHub. The arguments -u origin main tell Git that you want to push to your repository on GitHub (origin), and specifically the main branch. Git will remember and reuse these parameters when you run git push from this copy of the repository in the future.

From here on out, you can add, commit, pull, and push as usual to manage your repository. In the (hopefully) unlikely event that we need to fix a bug in the code that we provide, we’ll update the upstream repository and ask you to run git pull upstream main, to pull changes to the upstream code into your local copy.

Acknowledgments¶

Many CS 121 instructors and TAs have worked on this tutorial over the years. Gustav Larsson (PhD ‘17) and Isha Mehrotra (SB’19) deserve special mention. Gustav wrote the original version of this tutorial and Isha wrote the original material on branches and merge conflicts.

Introduction to Git¶

Where should you do this tutorial?¶

Getting started¶

Creating an SSH Key¶

Uploading your SSH key to GitHub¶

Creating your first repository¶

Initializing your repository¶

Creating a commit¶

git add revisited and git status¶

Working from multiple locations¶

Discarding changes and unstaging¶

Looking at the commit log¶

Merge conflicts¶

Working with upstream repositories¶

Acknowledgments¶

`git add` revisited and `git status`¶