Git is a widely used software version control system that is used when people in groups develop software together. Most open source and proprietary software systems are developed with some sort of version control system, with Git being the most popular.
At Rhodes, many professors use Git as a framework for distributed skeleton code and collecting programming assignments.
The documentation here is a small glimpse into programming with Git – enough to get started. For a more detailed treatment, check out the free online book: https://git-scm.com/book/en/v2
Creating a Github Account
Before we begin, you will need to create your own user account on http://github.com. Head over there and sign up a new account. Your userid on GitHub doesn’t have to be your full name or the same as your Rhodes ID, but it should be professional. It is likely that as you develop software, you will want to share your work with potential employers.
Once you have your Git login, you will need to configure some security settings so you can checkout and submit changes to GitHub repositories.
Configuring Github SSH Keys
GitHub is a cloud-based service which stores copies of your software in places called repositories. Typically, you will either accept an assignment through GitHub Classroom, or you may simply create a new repository directly on GitHub.
To work on the software, you will clone a copy of the repository on whatever machine you will be developing on, make changes, and then commit them back to the GitHub repository. In order for this to happen securely, GitHub needs to know that you are really you, and that it’s the same you that created a userid on GitHub. To ensure that communications between your local repository and the GitHub version are secure, Git uses the SSH protocol to guarantee that communications are authenticated and encrpyted.
To this end, SSH supports encryption keys. To get started, you create a new pair of keys: a public key and a private key. Any message encrpyted (written) with one key can only be decrypted (read) with the other key. The private key is protected by a passphrase (i.e. a password), but anyone can use your public key. In general, the public key is just that: public. If anyone on the Internet uses your public key to encrypt something, it can only be read with the private key (which is you). Likewise, if you encrypt something with your private key, then anyone on the Internet can read it, but they will know for a fact that you sent it (because only you can use your private key).
This documentation is geared towards students that are using cslogin for their coursework. If you are using Git on your laptop for your coursework, you will still need to configure Git with your SSH keys. If you haven’t created your SSH keys on your laptop/desktop you should follow the information in the Getting Started guides:
Creating A New SSH Key Pair on cslogin
FIrst off, start by logging into cslogin. Next, create an SSH keypair:
$ ssh-keygen -t rsa -b 4096
This will prompt you to make a passphrase. This is similar to a password, but should be longer and stronger. Make it something you won’t forget, but don’t worry – you won’t be typing it all the time like a normal password.
Once this is complete, we need to view the contents of public key, so we can copy it over to GitHub:
$ cat ~/.ssh/id_rsa.pub
It should look something like this:
ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAklOUpkDHrfHY17SbrmTIpNLTGK9Tjom/BWDSU GPl+nafzlHDTYW7hdI4yZ5ew18JH4JW9jbhUFrviQzM7xlELEVf4h9lFX5QVkbPppSwg0cda3 Pbv7kOdJ/MTyBlWXFCR+HAo3FXRitBqxiX1nKhXpHAZsMciLq8V6RjsNAQwdsdMFvSlVK/7XA t3FaoJoAsncM1Q9x5+3V0Ww68/eIFmb1zuUFljQJKprrX88XypNDvjYNby6vw/Pb0rwert/En mZ+AW4OZPnTPI89ZPmVMLuayrD2cE86Z/il8b+gw3r3+1nKatmIkjn2so1d01QraTlMqVSsbx NrRFi9wrf+M7Q== user@mylaptop.local
Adding Your SSH Keys to GitHub
Next, head over to http://github.com/ and login if you aren’t already logged in. Next, click on the profile picture image in the upper right corner of the window. You should see a menu like this:
Click on the Settings link, near the bottom. On the right, you should see a list of subcategories:
Click on the link for SSH and GPG keys. You should see a window like this:
Click on the link to add a New SSH Key. Then fill out the form giving your key a name, and pasting the text from cslogin you printed out above. It should look something like this:
Add this key and you should be all set to check out code from GitHub.
Note: Some cut/paste will break up the key text into multiple lines, which is incorrect. If you paste your key and it looks like this:
You will need to fix it first. Just go to the end of each line (after ssh-rsa) and remove the newline. The key next must be all on one line.
Git Command-Line Configuration
We’re almost there. Git will want you to setup a few pieces of information that will be used to identify your contributions. On cslogin, run the following commands:
$ git config --global user.name "John Doe" $ git config --global user.email johndoe@example.com $ git config --global pull.rebase false
Replace the John Doe information with your name and email address. The last line just avoids warning messages when you are merging code.
Git / GitHub / GitHub Classroom Basics
Getting and Assignment from GitHub Classroom
When you are assigned a new programming assignment on GitHub Classroom, you will be given a link from your professor to “accept the assignment”. This will create a new copy of the assignment repository with your name on it and linked to your GitHub account. This should land you on GitHub with at the project repository page. You should see a green button with the word Code on it:
Next, you will need to download this onto your development machine. Click on the green button and make sure SSH is underlined. Click on the copy link in the field with the string that starts with git@github.com:
Then, on cslogin you can type in git clone and paste the rest of the text. It should look something like this:
$ git clone git@github.com:Rhodes-CS-Professor/comp123-lab1-john-doe.git
If it all went well, you should now have a folder called comp123-lab1-john-doe in your current directory with the starter code for the assignment. You can rename and move this folder as you would like.
Creating Your Own Repository
To create your own repository, simply head over to GitHub and click the green New button on the upper right side. Fill out the fields regarding repository (project) name and visibility. Once created, it will take you to the new repo and you should have a green Code button as above to clone this locally.
Adding, Committing and Pushing Files
Once you have the repository cloned locally, you can use your normal workflow to add new files and modify existing files as needed to complete your assignment.
Git is a distributed version control system, which means that there are two repositories for your assignment. One is locally (or on cslogin) and the other is located on GitHub. To fully submit your work, you must add it to your local repository first, then push the changes back up to GitHub.
When you create or modify a file, the first thing you need to do is to tell Git that you want to select those files as a part of the working set. The other operations only work on files on the working set. To mark files in the working set, use git add. You can call git add multiple times to add more files to the working set. (You can remove everything from the working set and start over again by running git reset)
Next, once you have specified the working set, you need to commit it to your local Git repository. For this you will use git commit. This command will require you to write a short commit message which briefly documents the changes you made.
You should regularly commit your changes and updates locally. This is just a good practice and keeps several known good versions of your code as backup. You should commit whenver you have made a significant change and your code is a stable(ish) state.
Lastly, we use git push to replicate our local changes back up to GitHub. This is how your assignment is submitted for grading, if you are using GitHub Classroom.
Here is an example of cloning an empty repository, creating a file, and pushing it back to GitHub. Some whitespace has been added to make the example flow better and be more readable.
$ git clone git@github.com:example/example.git Cloning into 'example'... warning: You appear to have cloned an empty repository. $ cd example $ ls $ echo "hello, world" > hello.txt $ ls hello.txt $ cat hello.txt hello, world $ git status On branch main No commits yet Untracked files: (use "git add <file>..." to include in what will be committed) hello.txt nothing added to commit but untracked files present (use "git add" to track) $ git add hello.txt $ git status On branch main No commits yet Changes to be committed: (use "git rm --cached <file>..." to unstage) new file: hello.txt $ git commit -m "this is a one line commit message" [main (root-commit) 0f31fb5] this is a one line commit message 1 file changed, 1 insertion(+) create mode 100644 hello.txt $ git status On branch main Your branch is based on 'origin/main', but the upstream is gone. (use "git branch --unset-upstream" to fixup) nothing to commit, working tree clean $ git push Enumerating objects: 3, done. Counting objects: 100% (3/3), done. Writing objects: 100% (3/3), 238 bytes | 238.00 KiB/s, done. Total 3 (delta 0), reused 0 (delta 0), pack-reused 0 To github.com:example/example.git * [new branch] main -> main
Pulling in Updates from the GitHub Repository
The last stop on our (very) brief overview of Git is how to merge updates from the GitHub repository into your local version. You may need to do this if your professor updates the starter code and/or you are working with multiple developers and need to integrate their contributions into your local repository.
This operation is pretty simple:
$ git pull
Usually this will go off without a hitch, but it’s possible that you have local modifications to a portion of your code that someone else also modified. These are called merge conflicts and require special care to resolve (and is outside the scope of this tutorial).