Lab 6: Working with Git
Objectives
The objectives of this lab are:
Understand the importance of using version control in individual and group software development projects.
Set up and use Git for version control for projects where there is only one developer.
Set up and use Git for version control for projects where there are multiple developers.
1 Lab Introduction
This is a self-paced lab, with two parts. The first part is about setting up Git for your individual projects. You should complete this part in the week when this lab is scheduled. The second part is about setting up Git for group projects. You should complete that part only when the group assignments begin, with your chosen/assigned partner.
This lab has no required submissions, and therefore no grade associated with it.
The actual lab on that day will just be office hours so you can work on your project!
For both parts, you are responsible for guarding your work by keeping repositories private, and providing access only to your partner, only for code that will be written together. You are not allowed to provide access to your individually developed code, even to your group partner! Guard your intellectual property, and prevent your work from being used unfairly by others.
2 Why version control?
As we develop any documents, including source code, we must manage versions. Often we would like to “save” a working version before we make any changes, so that we may revert to them at any time. We wish to save incremental versions of a document. If documents are being developed as part of a team, it is desirable for each team member to independently work on documents, while being able to merge them with others’ versions. All of this needs special version control software. Version control software is an essential tool in today’s software development. It can be used for small single-person projects, as well as large team-projects. It can be used to maintain versions of virtually any type of file.
Examples of version control software include git, svn, Perforce, etc. In this lab we will learn how to work with git.
3 Terminologies
We begin by reviewing some common terminology (some of this is git-specific, but most terms are applicable to other version control software):
Repository (repo for short): A repository is the main storage for the software. A repository stores all saved versions of all documents currently under version control.
It is typical to have one repository per large project. You may also have one repository per course, etc.
Local repository: This is a repository that is stored on your computer (locally).
Remote repository: This is a repository that is stored at a remote location, most often in a web location. This allows you to retrieve versions of documents if your computer crashes. This also allows collaboration between people working on the same documents on different computers.
The remote repository is usually offered as a service. For example, github and bitbucket are two online services that offer remote git repositories.
In git, a remote repository is synchronized across multiple local repositories on different computers (belonging to people working on the same project).
Working copy: A working copy is the latest version of a document in the local repo. This may refer to the latest version of a single file, or a set of latest versions of multiple files.
4 Installing Git
Please complete this section individually.
Please follow these steps to install Git on your machine.
Go to Git, download and install Git on your machine.
Verify that Git has been installed correctly on your machine:
Windows users: Open File Explorer. Go to any directory and right-click. You should see new options in the menu that appears: “Git Gui Here” and “Git Bash here.” Select “Git Bash here.” A command prompt will open. Go to the third step.
Mac/Linux users: Open a terminal.
Type
git --helpand press Enter. If you see various options given by git, it has been installed on your computer correctly. If it does not recognize the command, then the installation has problems. Please consult a TA.
5 Getting used to the command prompt/terminal
It is highly recommended that you operate git from a command prompt/terminal, instead of with IntelliJ. Operating from the command prompt/terminal will also help you understand and remember git commands better.
Some common tips for using command prompt/terminal:
Knowing where you are:
Windows: the command prompt will tell you which folder you are currently in.
Mac/Linux or on the Windows Git bash prompt: type pwd and press Enter at any time to know which folder you are in (pwd stands for Print Working Directory).
Contents of current folder:
Windows: dir. The command dir /all will show all contents of the current folder, including hidden files/folders.
Mac/Linux/Windows Git bash prompt: ls. The command ls -all shows all contents of the current folder, including hidden files/folders.
Navigating folders:
All platforms: cd namedir enters the provided folder, if it is inside the current folder. cd .. goes up one folder.
6 Git resources
Atlassian (a popular git vendor) provides excellent tutorials on Git: www.atlassian.com/git/tutorials. We highly recommend the sections “Beginner” and “Getting started.” This lab covers most of these topics.
There is also an excellent interactive tutorial on using Git: it lets you practice working with Git in a simulation in your browser, without making any changes to your computer. We highly recommend the Introduction Sequence, as well as Ramping Up #4, Mixed Bag #5, and then the rest of the exercises.
7 Part 1: Git for individual projects
Please complete this section individually now.
7.1 Creating a new Git repo for existing code
All your individual projects for this course should be inside one folder somewhere on your computer. If you have not organized them this way, please do so now by moving project folders into one folder.
Inside this folder, create two new folders called “individual” and “group.” Move all the project folders inside the “individual” folder.
Windows users: go to “individual,” right-click and select “Git bash here.” Mac/Linux users: open a terminal and navigate to the “individual” folder.
Type git init and press Enter. This creates a new blank, local repository inside the current folder.
To verify that a repo has been created, print the contents of the current folder including all hidden files/folders (look above for the command). You should see a hidden folder called “.git”. Do not touch this folder or any of its contents. This is where your local repo will be stored.
7.2 Putting files under version control
To put a new file under version control, or to save a new version of a file already under version control, we follow two steps. First we stage the file for saving. Then we save all staged files to the local repo. This saving operation is known as a “commit.” A single commit may contain (a version of) several files.
From the terminal/Git bash prompt, navigate inside the IntelliJ project folder for Lab 1 (create the project if you do not have it).
Stage the file “src/Person.java” by typing git add src/Person.java.
Stage the remaining files in the src/ folder similarly.
You can stage all the files inside a folder at once. To stage all files in the “test” folder, type git add test/.
Verify all the staged files by typing
"git status .
. You should see all staged files, followed by any unversioned files inside this folder.
Commit the staged files: type git commit -m "First version of Lab 1". This saves all staged files and associates the given message with the commit. The message will help us to identify this particular version of each file in this commit.
Open Person.java and remove the getYearOfBirth method along with its comment. This represents a “change” in your code.
Follow the above steps to stage and commit only Person.java. Be sure to use a different informative commit message!
Make any additional change to Person.java and then stage and commit this file again with a different informative commit message.
7.3 Inspecting previous versions of a file
We can “inspect” previously committed versions of a file, and then either choose to revert to one of them, or come back to the working copy.
Important: before you try this, make sure that your latest changes are committed. Failure to do so will overwrite the files and you may not able to recover them!
To view all committed versions of a file, use the git log command. For example, to view all committed versions of Person.java, type git log Person.java (on the prompt you must be in the folder that contains this file).
To view a shorter summary of versions, type git log --oneline Person.java.
For each version of the file you will see a commit number. You will see your commit message next to the commit number, which will help you to identify the version.
To inspect a particular version type git checkout commit-number Person.java. This will overwrite the current Person.java with that version. You can verify this by opening the file.
To inspect a different version type repeat the above command using another commit number.
If you wish to revert back to a particular version, first check it out like above, and then type git commit. This version will now become the working copy.
If you wish to go back to your current working copy, type git checkout master Person.java. The file will be restored to its working copy.
Use the above knowledge to recover the first version of the Person class and re-commit it as the new working copy.
8 Creating a remote repository
All commands above store versions on your local computer. You can now sync your local repository with a remote repository.
8.1 What to do
Go to github.khoury.northeastern.edu. Log in using your Khoury account username and password (the same one you use on the handins server). github.khoury.northeastern.edu is the github repository provided to all CS students. It allows you to create private repositories for free. Alternatively you can also create a student account on github.com using your northeastern email address.
Click on “New repository.” Give it a suitable name.
Be sure to make it private.
Click on “Create repository.” You will now see a Quick Setup page.
Open a terminal/Git bash prompt on your computer and follow the instructions under the section “..or push an existing repository from the command line.”
When you complete the instructions, you will be able to see all the saved files and their versions on the remote repo. This shows that you have successfully created and used a remote repository!
Local and remote repos communicate with each other through two commands: push and pull. Pushing pushes local commits to the remote repo, while pulling pulls commits on the remote repo to the local repo.
8.2 Typical workflow
You should use version control for contents of src/ and test/ folders in each project. It is not recommended to save IntelliJ project files (*.iml) and .idea folders, since they may be specific to your version of IntelliJ. To tell git to ignore certain files, you can put a file named .gitignore in your repository (in the folder that has the hidden .git folder, not inside the .git folder). You will want to list all automatically generated files, such as the .iml and .idea files generated by IntelliJ, in the .gitignore. A sample .gitignore for Java is available for download.
When you create a new class/interface, stage and commit it (using git add and git commit -m ... commands).
If you are working on a certain feature (e.g. a new method, tests for a class, etc.) stage and commit only when you have it working. Usually you want commits to represent incrementally working versions that you may want to revert to, not rough work.
Before stopping your work for the day, or at suitable times, push your changes to the remote repo (using git push origin master).
9 Part 2: Git for group projects
Complete this with your partner, only when the group assignments start and you know who you will be working with.
Both partners should have the “group” folder from the earlier section. You will save all your group projects within this folder.
One partner can act as the originator of the project. This person will “start” the project.
Originator: create a new git repo within their “group” folder, using git init as before.
Originator: create a new project in this folder, add some files, stage and commit them.
Originator: create a remote repo on github.khoury.northeastern.edu (or github.com if you so chose above) for this group. This should be separate from the individual repo created earlier.
Originator: add the partner as a collaborator to this repo. To do this, go to Settings -> Collaborators. Give your partner write access to the repo. You will need your partner’s github username for this purpose.
Originator: push to the remote repo.
Note the address to the remote repo (it should be whatever the originator used in the git remote add https://... command to push the local repo).
Other partner: open a terminal/Git bash prompt. Navigate to your “group” folder (which should be empty)
Other partner: type
git clone url .
, replacing url with the address of the remote repo (don’t forget the . at the end!). It will now replicate the remote repo in the current folder (.), which should be your “group” folder. It will ask you for your github username and password.
Other partner: you should now have a folder with the same name as what the originator created for the project, with the src/ (and possibly test/) folders inside it. Open IntelliJ and select New -> Project from Existing Sources. Point it to folder that contains src/ and test/ and follow the prompts. This will create an IntelliJ project that uses those files.
Other partner: make a change to one of the files, stage and commit changes. Now push to the remote repo. You may have to add the remote repo using the command git remote add remote-repo-url similar to how the originator had to add when pushing onto the remote repo.
Originator: pull from the repo using the command git pull. You should now see the changes made by the other partner in your files.
Both partners should periodically stage and commit their local changes (using git add followed by git commit -m ...). Before beginning to work, pull from the remote repo to make sure you have all the latest changes made by your partner (using git pull). Similarly, push to the remote repo at least once before you are done (using git push origin master), so that your partner can pull your work.
10 Merge conflicts
It may happen that both partners work on the same file, commit their changes and push. The first one to push to the remote repo will succeed. When the other partner attempts to push (after committing all their changes), the remote repo will reject the request by warning that they do not have some versions that are on the remote repo. In this case, the partner who attempts to commit later must first pull from the repo.
Many times git is able to automatically merge versions. But sometime it fails and reports a merge conflict. When this happens, it inserts markers in the file that illustrate which parts are different in the conflicted versions. One must then go through the file, look at the marked regions and edit the file to retain the most suitable versions. Then this merged file must be staged and committed, and finally pushed out. In this way a user must manually resolve merge conflicts.
You can try to simulate this situation by simultaneously editing overlapping sections of the same file on your respective computers, committing them and attempting to push them to the remote repo.
11 Understanding practical workflows
Atlassian provides a useful overview of workflows using Git. Please read the tutorial and discuss with your partner.
12 Optional: Branches
Read the tutorial on branches on Atlassian. With your partner, create a new branch and make some commits to it. Then merge this branch onto the master branch.