Note: This tutorial is based on the EECS 280 Git Tutorial from Lab 0. All credit goes to James Juett and Zachary Goldston for designing the original lab.
One of the most important tools used in Software Engineering is Version Control Software, or VCS. (You'll also see it referred to as "VC" in this tutorial) VCS's function is to host and track a project over time. With it, developers can compare file changes, propose changes, view project history, track commits, more easily manage larger scale projects with several people, and more. There exist 2 main VCS today: Git and SVN. We will use Git on MRover, though SVN is another valid option for VCS.
Before beginning this exercise, we recommend going through the main README in the workflow-intros repository, to get some basic exposure to git.
For the purposes of these exercises, we recommend you work in groups of 2-3 to go through this tutorial. This way, you and your group will gain a basic understanding of Git Workflow and handling code changes across different remotes/computers. For the purposes of this tutorial, we will assume a group of 3, but feel free to adjust roles to the number of people in your group.
All group members should verify git is properly installed via the command git --version in your terminal. Additionally, all group members should configure their git profile, if not done yet. You can do this by running the two commands:
git config --global user.name "username"
git config --global user.email "youremail"
(Replace the username and youremail parts with the GitHub username and email you plan to use when working on MRover! Note that we do not use Michigan's GitHub server)
Everyone in the group should sign into their GitHub account they plan to use with the MRover team, if they have not done already.
Person 1 should create a new repository on GitHub. From here, Person 1 should ensure the following when creating the new project:
- Name it
mrover-vc-exercise - Set it to private.
- Select the "Add a README file" option. Make sure it is checked before creating.
Once Person 1 has created the repository, the next step is to add the other members of the group. Click on the three dots towards the right of the newly created repository page, select "Settings," then "Collaborators," and then "Add people." You will want to add them via username, assuming everyone in the group has made a GitHub account. Once done, you all have access to your remote repository, where you can put your exercise code that lives "in the cloud."
To actually work on the code, you will need to clone the remote repository to create a local repository on your own computer.
- Open a terminal and navigate to a folder. We recommend making one called
mroverto store all the work you will be doing with us. - Run the following command (replace
zwgoldwith the username of the person who had created the remote repository):git clone [email protected]:zwgold/mrover-vc-exercise.git(Note: This command will only work if you have SSH Keys set up. Please follow the steps in the first tutorial to do so!) Alternatively, (and probably more common) you can get the link from the browser page of the repository by clicking on the green Code dropdown button, selecting SSH under the "Clone" word, and then clicking the copy button next to the generate link. (should be two squares overlapping) You can then paste this into your terminal by right clicking, rather than typing out or copying then modifying the command above. - Enter your username and password if prompted.
This should create a new folder called mrover-vc-exercise. That is your local repository.
At this point, everyone should have a new directory for the local repository called mrover-vc-exercise. Navigate your terminals into that folder using cd mrover-vc-exercise. You can check that you are in the right place with the command pwd.
Everyone run git status. We will run this frequently, and you should make a habit of it - it's a
good way to check the state of your local repository. You should see that you are up-to-date with
origin/main (the "origin" refers to the remote repository on github).
Run the command ls. You should see the default README.md file that GitHub created automatically with the project. Feel free to go ahead and open the file in your IDE. (You could also just open the whole folder in your IDE.)
README.md contains a bunch of project startup suggestions from GitHub. You'll also notice that
the raw text of the file is in a lightweight markup language called Markdown.
Person 2 should edit their copy of the file to remove mostly everything and replace it with a simple list of your group members. For instance:
# mrover-vc-exercise
Our members in our group are Zachary Goldston, Cameron Tressler, and Ashwin Gupta.
Make sure to save the file with your changes. (Here and any time you make changes!)
Everyone run git status. Person 2, who had made the changes, should see there are changes to README.md.
Person 2 should continue to lead for this section. Others should follow along.
- Run
git add README.md. This stages the changes so they can be committed. - Run
git status. This shows that file is now staged from the previous step, and it is ready to be committed. - Run
git commit -m "modify readme". This commits the changes to your local repository. You can think of each commit in the repository as a step along the version history of your code. The-madds a note about what the commit does. - Run
git status. This shows that after performing the commit command, your local repository is a step ahead of the remote repository. - Run
git push origin main. This will send your commit from your local repository to the remote repository on themainbranch. Alternatively, you can also rungit push, though you may be asked to configure your upstream, which if needed, a message will pop up with the corresponding command to do so. (Might also need to put a username and password for GitHub) An "upstream" refers to the point where it originated from, or where we can send local commits to remote repositories. For us,originis the upstream since we have our own remote repository. - Run
git status. Everything at this point should be in sync again.
Now, everyone check out the repository on GitHub's website. The changes should now be there!
Everyone except the person (Person 2) who ran the commands in the last step should run git status. git running on your local machine has no idea about the changes that are now on GitHub. You need to manually tell it to
check in with the remote.
- Run
git fetch. This fetches information from the remote repository to update your local repository. Rungit statusagain - you're 1 commit behindorigin/main. - Check your
README.mdfile. It hasn't changed yet. Your computer knows there are changes to origin/main that are ahead of your main, but it hasn't applied them. - Run
git merge. This merges the changes and actually updates your files to match.
Everyone's local README.md should be up-to-date. If you've got it open in an IDE or other editor, it's possible you might need to somehow refresh the file or close and reopen it.
Instead of the two steps above, you could have also used git pull. This is a shortcut for a
fetch followed immediately by a merge.
Make sure everyone is up-to-date via git status and has the updated README.md file before moving on. If something goes wrong or you get stuck, check in with us!
Person 2 and Person 3. should lead for this section. Others should follow along. Both of them should create a new file. Make sure to create files with different names, like person2.txt and person3.txt. Put some text in the files and make sure to save.
Now, Person 2 should contribute their new file via the normal process (add, commit, push). For example, let's say you had created person2.txt. You would run:
git add person2.txt
git commit -m "create person 2 file"
git push
Next, Person 3 should attempt the same. Everything works up until the push, where you'll get an error message. (Go ahead and try, so you can see the message.) That's because git does not allow you to push if you're not up-to-date with the remote. We can fix this.
To handle diverging branches, we will perform a "merge commit." With Person 2 having successfully pushed, but Person 3 unable to do so, we will need to resolve this. We can do this with the following steps:
- Person 3 should run
git fetch. Afterwards,git statusshould show diverged branches. - Now, Person 3 should run
git merge. This will create a new "merge commit" following from both diverged paths and bringing them back together. It will also pop open the terminal text editor (eithervimornano) to allow you to edit a message for this merge. - For now, just keep the default and close the editor. For
nano, press ctrl+x to close out. Forvim, hit the escape key, and then type:qand hit the enter key. - Now, Person 3 should make sure to push and everyone else should pull.
The changes have been successfully reconciled across different files! However, we still have one scenario to explore: What happens when two people edit the same file?
There's one more issue to consider when reconciling divergent commits - what if the commits are made to the same file, including potential contradictory changes!?
In this case, you've got a merge conflict. Regardless of whether you choose to rebase or merge, git is going to need some help figuring out what to do. For our purposes, we will not be covering rebasing (as rewriting commit history is bad) and only focus on merging. In fact, for the purpose of MRover, you should almost never need to rebase.
For this section, let Person 1 and Person 2 lead. Both should make sure you are up to date with the changes from the last section.
First, have Person 2 edit the README.md copy, as such:
# mrover-vc-exercise Person 2 was here.
Our members in our group are Zachary Goldston, Cameron Tressler, and Ashwin Gupta.
Also changing stuff here.
Additionally, make a new files called new.txt. Put whatever text you want in it.
Now, Person 2 should contribute their changes. The commands are as follows:
git add -A
git commit -m "person 2 changes"
git push
Note that the -A flag will stage all files that have been modified.
Now, before pulling from remote, Person 1 should make one change to their copy of README.md. They should not have pulled in the changes Person 2 just made.
# mrover-vc-exercise Person 1 was here, now.
Our members in our group are Zachary Goldston, Cameron Tressler, and Ashwin Gupta.
Before committing anything, Person 1 should run git pull. This will grab Person 2's changes, and attempt to merge them in.
You'll get an error message here, though. git won't let you do it, because it would overwrite the "Person 1 was here, now." changes that haven't been committed yet. The error message suggests
you "Please commit your changes or stash them before you merge."
(We won't cover git stash in this tutorial, though it would also be a viable option here. Essentially, the idea of a "stash" would be to hide away the Person 1's local changes, allow them to pull the Person 2's commit, and then reapply the stashed changes on top.)
From here, Person 1 should go run the following commands:
git add -A
git commit -m "Person 1 changes"
Person 1 should then run git pull again. This time, the fetch and merge will go ahead and attempt to reconcile the divergent branches.
You should see a message like this:
Auto-merging README.md
CONFLICT (content): Merge conflict in README.md
Automatic merge failed; fix conflicts and then commit the result
Additionally, if you run git status, you'll see that new.txt is all good, but that README.md is currently an "unmerged path" because there was a conflict.
To fix this, open up README.md in an editor or IDE. You'll see something like this:
<<<<<<< HEAD
# mrover-vc-exercise Person 1 was here, now.
=======
# mrover-vc-exercise Person 2 was here.
>>>>>>> 6af387196da8bd82792cdc5d121ee4f2defc9949
Our members in our group are Zachary Goldston, Cameron Tressler, and Ashwin Gupta.
Also changing stuff here.
Git has marked up your changes ("HEAD") and the incoming changes (">>>>>>> 6af387...") in the places where there were conflicts (i.e. two people edited the same line).
To resolve the conflict, ultimately you just need to put the file in the state you want. Depending on your editor, it might recognize the markup git has added and highlight the current vs. incoming change, or it might even give you shortcuts to accept one or the other.
Person 1 should keep the "Person 1 was here, now." part/version and also delete the git markup. The result is this:
# mrover-vc-exercise Person 1 was here, now.
Our members in our group are Zachary Goldston, Cameron Tressler, and Ashwin Gupta.
Also changing stuff here.
Make sure to save the file. Now, at the terminal run:
git add README.md (to mark the README.md conflicts as resolved)
git commit (to finish the merge commit)
An editor will open for the merge commit message. Close it out to return to the terminal command line. Finally, Person 1 runs git push to push their changes and the merge commit.
Everyone else can run git pull to get up-to-date!
Congratulations on making it through this tutorial! You and your group have the basic skills on how to handle different changes across different files, and even the same ones! If you want more great git tutorials, we recommend you check out this page.