CS 3410 Lab 0: Introduction to Git

CS 3410

---

Why Git?

Git is a version control software, and its primary purpose is to ensure that as you make incremental changes to files, you will always be able to revert to, see, and combine old versions. When combined with a remote repository (in our case Github), it also ensures that you have an online backup of your work. Git is also a very effective way for multiple people to work together: individuals can upload their work to a shared repository. (It certainly beats emailing or messaging versions back and forth!)

More advanced use of git allows features to be developed separately from the "master" branch, and only included when they are ready. This can all be done concurrently and distributed among multiple people.

We will use git in CS 3410 as a way of disseminating assignment files to students and as a common place for project partners to share, store, and backup their work.

Part 1: username, please!

Before we can create a repository for you in this class, we will need you to acvitate your Cornell github accout and tell use your username. If you've never used Cornell's github before and/or your don't know your Cornell github username, please read this page for an explanation of how to activate your account and find/change your username.

Think you know your Cornell github username? You should be able to see your own profile by going to: https://github.coecis.cornell.edu/your_username (You'll have to type your_username after the URL.)

Now go to CMS and fill out the Lab 0 survey.

Part 2: Gitting to know you

If you do not already have Git installed on your computer, install it from here.

There are a variety of good Git tutorials on the web (Codecademy, Github, and Bitbucket, to name a few). This one will provide a very basic intro to the most essential features of Git that you will be using in this course, but you are highly encouraged to delve into more depth, as you will definitely use Git or another version control software quite often as you continue in CS. If you are already familiar with Git, feel free to skim this, but you will be expected to know the basics of using Git.

Git Basics

Once we have everyone's Cornell github usernames, we will create individual repositories for each student inside a Fall 2018 Organization. We'll also create pair repositories for you and your partner for each paired project. In the meantime, however, go to your personal github page located at https://github.coecis.cornell.edu/your_username and create a repository that you can play with for the purposes of this tutorial. (You can delete it when you're done if you like.)

• Create a New Repository: go to the top right of the page, where you'll see a Bell, a Plus Sign, and your Profile Icon (which is likely just a pixely patterned square unless you uploaded your own.) Click on the downward pointing triangle to the right of the Plus Sign, and you'll see a drop-down menu that looks like this:
  
  Click on "New repository" and then create a new repository like this (assuming your username is abc123):
  
  Note that the default setting is to make your repository public (visible to everyone). Any repository that contains code for this course should be made private because a public repository shares your code with others which consistutes an academic integrity violdation.

  Now click on the green "Create Repository" button.

• Clone your Repository: Cloning a git repository means that you create a local copy of the contents of the repository. You're going to clone the repository you just created onto your own local machine. Locate the green button on the right that says "Clone or Download". Click it, then copy the link provided ("https://github.coecis.cornell.edu/abc123/play_repo.git"). In a terminal, navigate to the folder where you would like to put your repository, and type git clone https://github.coecis.cornell.edu/abc123/play_repo.git, replacting abc123 with your actual username. This will download the repository from the remote to your computer - you will need to type in your Cornell username and password in order to download it (and every time you make changes or pull down others' changes).

• A first glance at your Repository: Type cd play_repo to enter the repository.

  Type git status to see an overview of your repository. This command will show the status of your repositories and the files that you have changed.

  Type git log to see the history of the current repository. This will show you the author, time, and commit message for every commit, along with the commit hash, which is how Git labels your commits and how you reference them if need be.

  At this point, you won't see anything interested because you haven't actually changed any of the files in the repository.

• Tracking files with git: There are 3 steps to track a file with Git. All changes start out unstaged - this means Git is not aware of the changes to the file. Create a new file called new_file.txt in the root directory of the git repository, then type git add new_file.txt from the directory containing the file to stage the file.

  Now enter git status again, and you will see the file you added highlighted in green. This means that it is staged. You can stage as many files as you'd like - this is simply a temporary step before you make a commit, which is saving the state of all the staged files as they are right now.

  At any point, you can see the state of your repository by going back to to the github webpage: https://github.coecis.cornell.edu/abc123/play_repo. Notice that right now the repository has only one file: README.md. Because new_file.txt has been staged but not committed, it's not yet part of the repository. (This means that if you only add a file, your partner cannot yet see it, either!)

  A commit is a record of the state of the repository at a specific time. To make a commit, enter git commit -m "commit message here", where the commit message is an explanation of the changes that you have made since you last committed. Good commit messages help you and your partner know what you've just done.

  This commit is now on your local computer. If you refresh the webpage, you'll see it's still not on the remote repository. To add it to the remote (Github), enter git push. This will add your new commit to the remote repository, where you or anyone else who has access to the repository can view it. (Now if you refresh the github webpage, you'll see that new_file.txt is part of the repo.)

  Now, if someone has made changes since you last began work, enter git pull to pull down those changes and bring them into your local repository. If all goes well, this will bring your local repository up to date with the master, and you can continue making your own changes to later be pushed.

  Typical Usage Pattern

  Here is a good pattern for working in git:
  1. git pull: type this before you start working to receive any work that your partner did while you were sleeping
  2. Work on your shared files
  3. git add file.txt: type this for each file you either modified or added to the repo while you were working. Not sure what you touched or what's new? Type git status and git will tell you!
  4. git commit -m "very helpful commit message": to let your partner or your future self know how this version differs from the previous one
  5. git push: remember without the push, the changes stay local!

  What if I make local changes before doing a git pull?

  If you did make local changes but did not commit them and do not need the changes, you can type git stash to revert the changes back to the last commit. This does not delete your changes, but "stashes" them away. They can be retrieved, but it is often a bit of a process to do so, so make sure you've copied all the changes you'd like to keep first.

  If you did commit these changes, enter git reset COMMIT_HASH, where commit hash is the hash of the commit that the remote repository is at (something like eb6a5a8ad3b0e7cc0d694d44d3ab866129db5965), found using git log. This will undo the last commit, but leave the changes there, so see the section above for what to do from here.

  If you did git pull without realizing that you had made changes or that there were new changes in the remote repository, Git will merge the two together, combining the changes where it can. This works well for code, but it does not work at all for Logisim circuits (see next section). If you did git pull and now see CONFLICT (content): Merge conflict in FILE, this means you have a merge conflict - the changes that were made conflicted with each other. Type git merge --abort then see the first paragraph in this section.

  Git and Logisim

  Git was primarily created for software projects, but we will also be using it for Logisim, a visual circuit designer. This is a somewhat non-typical usage, but it provides great benefits in that it ensures that every student has a backup of their circuits, and that they can revert to a previous version if something goes wrong.

  Warning: Git doesn't know how to merge Logisim circuits. If you have made changes to a circuit locally and then try to pull down changes from the remote repository, the results will be uglier than the movie "The Fly" (google it if you're not faint of heart). Even if Git does not report a CONFLICT, the circuit almost certainly will not work in Logisim. Use the section above to revert the merge commit and the commits before that.

  So, do not work on your circuit without first pulling from remote, and do not work on your circuit concurrently on two computers and expect Git to merge the circuits for you. If you do, use Logisim's copy/paste feature to combine the two circuits manually, then commit the result to Git.

  It takes a long time to master Git. If you run into real trouble, don't be afraid to ask a TA or simply reclone the project. It's very easy to make Git do very strange things very quickly, but ultimately Git is an invaluable tool for any large project.